BMC Remedy Action Request System 9.1.00 PDF

BMC Software Confidential. BladeLogic Confidential.
BMC Remedy Action Request

System 9.1
Home
Date: 16-Dec-2015 04:24

URL: https://docs.bmc.com/docs/display/ars91
/Home
Home BMC Software Confidential. BladeLogic Confidential.
Contents
Release notes and notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Related topics: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Known and corrected issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
9.1.00 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Centralized configuration available for more parameters . . . . . . . . . . . . . . . 46
Improved functionality for BMC Remedy Deployment Application . . . . . . . . 47
Improved search relevancy for Multi-Form Search (MFS) . . . . . . . . . . . . . . 47
Enhancements to armonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Locating white papers, guides, and technical bulletins . . . . . . . . . . . . . . . . . . . 47
BMC Remedy AR System online documentation . . . . . . . . . . . . . . . . . . . . . 48
BMC Remedy Encryption online documentation . . . . . . . . . . . . . . . . . . . . . 52
BMC Remedy Migrator online documentation . . . . . . . . . . . . . . . . . . . . . . . 52
BMC Remedy IT Service Management Preconfigured Stack online
documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
White papers online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Product announcements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Statement of direction for Compatibility Matrix . . . . . . . . . . . . . . . . . . . . . . . 54
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
About BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Key concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Product overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
License overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Access control overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Application development overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
User goals and features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
User roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Available BMC Remedy AR System features and configurations . . . . . . . . . . 183
Features you can install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Configuration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Installation and upgrade paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
BMC Remedy Action Request System 9.1 Page 2 of 4838

Planning a server group installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Planning BMC Remedy AR System installation in an enterprise environment
198
BSM environment recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
BSM Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Mainframe integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
BSM Reference Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Security architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Security considerations for BMC Remedy AR System . . . . . . . . . . . . . . . . 210
General security guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
BMC Remedy Encryption Security options . . . . . . . . . . . . . . . . . . . . . . . . 220
Security policy impact on client-server communication . . . . . . . . . . . . . . . 221
BMC Remedy Encryption Security compatibility . . . . . . . . . . . . . . . . . . . . 222
BMC Remedy Encryption Security modifications to the JRE . . . . . . . . . . . 222
WhiteHat Sentinel PE security penetration testing . . . . . . . . . . . . . . . . . . . 223
Language information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Supported languages and character encodings . . . . . . . . . . . . . . . . . . . . . 231
Localized forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Installing BMC Remedy AR System in an international environment: Oracle
on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
BMC Remedy Email Engine internationalization support . . . . . . . . . . . . . . 234
BMC Remedy AR System standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
BMC Remedy AR System server standards . . . . . . . . . . . . . . . . . . . . . . . 235
BMC Remedy Mid Tier standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Support for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Post-installation or post-upgrade considerations . . . . . . . . . . . . . . . . . . . . 236
Supported operating systems for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Supported databases for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
IPv6 considerations with BMC Remedy AR System . . . . . . . . . . . . . . . . . 237
Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
About BMC Remedy ITSM Suite 9.1 Deployment online documentation . . . . 238
Configuring after installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Logging on to the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Modifying the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Working with BMC Remedy AR System licenses . . . . . . . . . . . . . . . . . . . . . . 243
Adding or removing licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Exporting or importing licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Displaying and Tracking server group license usage . . . . . . . . . . . . . . . . . 247
Reviewing license usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Generating a license usage report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Licensing for server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Configuring AR System servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Configuring clients for AR System servers . . . . . . . . . . . . . . . . . . . . . . . . . 257
Configuring firewalls with AR System servers . . . . . . . . . . . . . . . . . . . . . . 257
Running a stand-alone AR System server on Windows . . . . . . . . . . . . . . . 259
Configuring a server for alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Configuring the AR System server for external authentication . . . . . . . . . 260
Configuring a server to use plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Setting version control options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Setting timeout options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Setting a connection to the BMC Atrium SSO server . . . . . . . . . . . . . . . . . 266
Setting a connection to the BMC Atrium Web Services Registry . . . . . . . . 266
Setting platform options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Setting log files options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Setting server logging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Setting ports and RPC numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Setting database options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Setting currency types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Setting license options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Setting external authentication options . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Setting performance and security options . . . . . . . . . . . . . . . . . . . . . . . . . 285
Setting server passwords, RPC options, and plug-in timeouts . . . . . . . . . 288
Setting administrative options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Monitoring service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Defining queues and configuring threads . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Changing a server name when using a duplicated or migrated environment .
300
Setting security restrictions on file uploads . . . . . . . . . . . . . . . . . . . . . . . . 317
Setting server statistics options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Renaming the AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Setting Always On logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Configuring server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Configuring the server group check interval . . . . . . . . . . . . . . . . . . . . . . . . 344
Setting failover rankings for servers and operations . . . . . . . . . . . . . . . . . 345
Signaling mechanism in a server group . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Configuring full text search for a server group . . . . . . . . . . . . . . . . . . . . . . 349
Configuring DSO for a server group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Configuring the Email Engine for a server group . . . . . . . . . . . . . . . . . . . . 353
Configuring flashboards for server groups . . . . . . . . . . . . . . . . . . . . . . . . . 353
Bypassing the load balancer to work on a specific server . . . . . . . . . . . . . 354
Using data archiving with server groups . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Configuring logging for server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Removing a server from a server group or remove an unused server name . .
356
Sharing a database without using a server group . . . . . . . . . . . . . . . . . . . 356
Configuring java plug-in servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Creating Java plug-in sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Setting global plug-in server options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Setting plugin server configuration options . . . . . . . . . . . . . . . . . . . . . . . . 361
Working with Java plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Working with Java plug-in sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
BMC Remedy AR System cache management . . . . . . . . . . . . . . . . . . . . . . . 369
Configuring the server cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Guidelines for resolving cache memory issues . . . . . . . . . . . . . . . . . . . . . 373
Running the ViewStat utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Setting the distributed mapping cache refresh interval . . . . . . . . . . . . . . . 377
Setting the distributed mapping cache refresh interval 9.1 . . . . . . . . . . . . 377
Actions that trigger cache events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Mid Tier cache configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Actions in ITSM 7.0.00 applications that trigger caching . . . . . . . . . . . . . . 392
BMC Remedy Mid Tier configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Configuring BMC Remedy Mid Tier as a shared service . . . . . . . . . . . . . . 393
Onboarding a new tenant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Offboarding a tenant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Configuring the mid tier through a firewall . . . . . . . . . . . . . . . . . . . . . . . . . 424

Configuring mid tier memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Accessing the Mid Tier Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . 427
Configuring the Change Password page . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Configuring the Overview page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Configuring the General Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Setting pagination properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Configuring the AR Server Settings page . . . . . . . . . . . . . . . . . . . . . . . . . 436
Configuring the Cache Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Configuring the Report Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Configuring the Web Service Settings page . . . . . . . . . . . . . . . . . . . . . . . 461
Configuring the Connection Settings page . . . . . . . . . . . . . . . . . . . . . . . . . 462
Configuring a mid tier to launch a browser in a different mid tier . . . . . . . . 465
Cookies used by BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Settings in the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
Setting up a cluster with multiple tenants . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Configuring a hardware load balancer with BMC Remedy AR System . . . . . . 489
What a load balancer does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
How load balancers route requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
Considerations for configuring load balancers with AR System servers . . 491
Using a load balancer with server groups . . . . . . . . . . . . . . . . . . . . . . . . . 492
Load balancer configuration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Sample load-balancer- Cisco 11500 Series Content Services Switch . . . . 499
Special considerations and known issues . . . . . . . . . . . . . . . . . . . . . . . . . 501
Load balancing with Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507
f5 load balancer sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Configuring a Unicode server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Running your Unicode server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
How BMC Remedy AR System works with Unicode . . . . . . . . . . . . . . . . . 513
Specifying a character set for data import to a Unicode AR System server . . .
517
Filter and escalation workflow considerations . . . . . . . . . . . . . . . . . . . . . . 519
BMC Remedy SNMP Agent configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
SNMP introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
SNMP access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Monitoring BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Sending traps to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

SNMP configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
arsnmpd configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
snmpd configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
armonitor configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Starting the SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Stopping the SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
SNMP Configuration form in the AR System Administration Console . . . . 532
Configuring BMC Remedy Distributed Server Option . . . . . . . . . . . . . . . . . . . 535
Setting up DSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Enabling DSO on an AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
Configuring a password for the DSO user . . . . . . . . . . . . . . . . . . . . . . . . . 538
Assigning an RPC program number to DSO . . . . . . . . . . . . . . . . . . . . . . . 538
Configuring remote AR System servers for DSO . . . . . . . . . . . . . . . . . . . . 539
Configuring DSO for firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Specifying a DSO host name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Configuring the RPC timeout setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
DSO for load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
AR System Administration - Server Information form - DSO tab . . . . . . . . 544
Configuring full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
FTS tab configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
High-availability architecture for FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
FTS Configuration form in the AR System Administration Console . . . . . . 552
Creating index files in a different directory from the default . . . . . . . . . . . . 555
Scheduling scans for updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Configuring the Ignore Words List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Displaying FTS weight in a results list . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Providing a shortcut for specifying expanded FTS qualifications . . . . . . . . 557
Configuring FTS for localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Advanced FTS configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Adding FTS licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Configuring reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
Modifying the config.properties file for limiting report entries . . . . . . . . . . . 562
Limiting entries using a published report . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Configuring web and BMC Remedy AR System reports . . . . . . . . . . . . . . 563
Using Crystal reports with BMC Remedy AR System . . . . . . . . . . . . . . . . 581

Managing localized Crystal and Web reports . . . . . . . . . . . . . . . . . . . . . . . 591

Configuring the BMC Remedy Approval Server . . . . . . . . . . . . . . . . . . . . . . . 595
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Working with the AP-Administration form . . . . . . . . . . . . . . . . . . . . . . . . . . 596
Process administrator overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
Configuring process administrator capabilities . . . . . . . . . . . . . . . . . . . . . . 598
Configuring Approval Server to work with flowcharts . . . . . . . . . . . . . . . . . 599
Configuring BMC Remedy Approval Server with a separate plug-in server
instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Starting and stopping the Approval Server . . . . . . . . . . . . . . . . . . . . . . . . . 602
Configuring BMC Remedy Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Configuring outgoing mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
Performance and configuration settings for Email Engine . . . . . . . . . . . . . 609
BMC Remedy Email Engine mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Saving outgoing notifications in MAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Changing the default time interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Testing your mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
Configuring incoming mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627
Stopping and starting the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Identifying the Email Engine component . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Modifying the companionservername or RMIPort properties . . . . . . . . . . . 634
Configuring BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Setting up flashboard update intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Starting or stopping the Flashboards server manually . . . . . . . . . . . . . . . . 636
Setting up a headless environment with Tomcat to display flashboards . . 637
Configuring the display properties for a flashboard . . . . . . . . . . . . . . . . . . 637
Modifying the config.properties file for flashboards . . . . . . . . . . . . . . . . . . 644
AR System Administration - Flashboard Server Configuration . . . . . . . . . 645
Multiple Flashboards servers and AR System servers . . . . . . . . . . . . . . . . 646
Configuring BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Removing an AR System server and its BMC Remedy Migrator license from
view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Adding AR System server into server account . . . . . . . . . . . . . . . . . . . . . . 648
Adding a licensed AR System server in BMC Remedy Migrator . . . . . . . . 650
Adding or transferring BMC Remedy Migrator license to an AR System server
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

Starting BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

Setting-up BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Configuring the Assignment Engine server settings . . . . . . . . . . . . . . . . . . . . 653
AR System Assignment Engine: Server Settings form . . . . . . . . . . . . . . . 653
Assignment Engine log file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Configuring BMC Remedy Single Sign-On . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Using BMC Remedy AR System for Authentication . . . . . . . . . . . . . . . . . . 655
Using SAMLv2 for authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Using Kerberos for Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Using LDAP for authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Managing Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Securing BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Configuring SSL for the email engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Resetting the Application Service password . . . . . . . . . . . . . . . . . . . . . . . 684
Securing incoming and outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Configuring BMC Remedy Encryption Security . . . . . . . . . . . . . . . . . . . . . . . . 689
Configuring the data key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
Configuring the public key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Activating encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
Deactivating encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Activating FIPS compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Using Oracle CLOBs with BMC Remedy AR System . . . . . . . . . . . . . . . . . . . 697
About Oracle LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
Storage size impact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
Performance impact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
Converting LOB storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Monitoring API calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
To monitor API calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
To view API call details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
About BMC Remedy ITSM Suite 9.1 Deployment online documentation . . . 710
Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Integration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
Where to integrate BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . 714

Multiplatform issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716

Choosing an implementation method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Integration technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Enabling plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
AR System plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Plug-in types supported by BMC Remedy AR System . . . . . . . . . . . . . . . 720
AR Filter API plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
AREA plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
ARDBC plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
Installed plug-in components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Creating C plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
C plug-in naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Configuring the Java plug-in server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Creating Java plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Configuring the AR System server to access a plug-in server . . . . . . . . . . 782
Running the plug-in server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
Common plug-in C functions and Java methods . . . . . . . . . . . . . . . . . . . . 786
Opening Knowledge Management System Configuration form . . . . . . . . . 788
Integrating with a directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
LDAP plug-ins in BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . 789
Using the ARDBC LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Configuring the ARDBC LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Building BMC Remedy AR System forms for directory services . . . . . . . . 793
Using the AREA LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
ARDBC LDAP example - Accessing inetorgperson data . . . . . . . . . . . . . . 806
Integrating BMC Remedy Single Sign-On with other BMC products . . . . . . . 812
Integrating BMC Remedy Single Sign-On with BMC Remedy AR System 812
Integrating BMC Remedy Single Sign-On with BMC Remedy Mid Tier . . . 815
Integrating BMC Remedy Single Sign-On with BMC Remedy with Smart IT or
BMC MyIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818
Integrating BMC Remedy Single Sign-On integration with BMC Analytics for
BSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
Migrating from BMC Atrium Single Sign-On to BMC Remedy Single Sign-On
826
AR System external authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
Enabling AREA authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

Configuring authentication processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

Setting up the AREA hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Enabling FIPS support for BMC Atrium SSO . . . . . . . . . . . . . . . . . . . . . . . 837
Data and database integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
Creating vendor forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
View forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
SQL database access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
ODBC database access introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
Extending BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . . 862
Creating plug-ins to extend BMC Remedy Developer Studio . . . . . . . . . . 863
Prerequisites for creating plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
Extension points for BMC Remedy Developer Studio . . . . . . . . . . . . . . . . 866
Developer Studio Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
Installation directory for the BMC Remedy Developer Studio plug-ins . . . . 867
BMC Atrium Orchestrator integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
Defining BMC Atrium Orchestrator web services . . . . . . . . . . . . . . . . . . . . 869
Modifying entries in the AR System Orchestrator Configuration form . . . . 871
BMC Remedy AR System workflow for BMC Atrium Orchestrator integration .
872
Obtaining job status for asynchronous execution operations . . . . . . . . . . . 875
Running external processes with the Run Process action . . . . . . . . . . . . . . . 876
Running external processes introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 876
Triggering Run Process on clients and servers . . . . . . . . . . . . . . . . . . . . . 877
Starting applications with the Run Process action . . . . . . . . . . . . . . . . . . . 877
Retrieving data from applications with Run Process . . . . . . . . . . . . . . . . . 880
Using Run Process for the web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883
Integrating the BMC Remedy Assignment Engine into an application . . . . . . 885
To integrate the BMC Remedy Assignment Engine with your application . 885
Preparing for the auto-assignment process . . . . . . . . . . . . . . . . . . . . . . . . 885
Adding fields to the assignee and request forms . . . . . . . . . . . . . . . . . . . . 886
Adding assignee and request forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Adding assignment rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
Setting sequencing for rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
Adding and executing assignment processes . . . . . . . . . . . . . . . . . . . . . . 893
Using DSO with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894
Setting up DSO to use CMDB data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895

Join forms and BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895

Writing to the CMDB production dataset . . . . . . . . . . . . . . . . . . . . . . . . . . 896
Examples of using DSO to replicate CMDB data . . . . . . . . . . . . . . . . . . . . 897
Recommendations for using DSO with BMC Atrium CMDB . . . . . . . . . . . 899
Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900
Using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
Navigating the BMC Remedy AR System interface . . . . . . . . . . . . . . . . . . . . 901
Using the AR System Object List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
Opening Approval Central . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
Copying field information to a new request . . . . . . . . . . . . . . . . . . . . . . . . 925
Running and saving searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
Finding a request by example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
Running a saved, recent, or defined search . . . . . . . . . . . . . . . . . . . . . . . 930
Loading search criteria without execution . . . . . . . . . . . . . . . . . . . . . . . . . 931
Saving searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
Managing saved searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
Running searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
Types of searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
Using the advanced search bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934
Reporting on BMC Remedy AR System data . . . . . . . . . . . . . . . . . . . . . . . . . 943
BMC Remedy AR System Report Console . . . . . . . . . . . . . . . . . . . . . . . . 943
Report designer screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
Report types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
Running reports in the Report Console . . . . . . . . . . . . . . . . . . . . . . . . . . . 946
Creating reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
Editing and deleting reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
Scheduling reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972
Publishing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 973
Saving or exporting BMC Remedy AR System reports . . . . . . . . . . . . . . . 975
Using a BIRT editor to create or modify web reports . . . . . . . . . . . . . . . . . 976
Approving requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
Approval notification through email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018
Configuring the Request ID link on Approval Central . . . . . . . . . . . . . . . . 1022
Setting previews for approval requests . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Processing approval requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Using the Get Agreement sample application . . . . . . . . . . . . . . . . . . . . . 1043

Using BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051

Viewing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
Sorting flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052
Refreshing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
Displaying tooltips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
Manipulating BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . 1057
Drilling down to information in a flashboard . . . . . . . . . . . . . . . . . . . . . . . 1058
Administering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
Navigating the BMC Remedy AR System Administration console interface . 1060
Opening the AR System Administration Console . . . . . . . . . . . . . . . . . . . 1060
AR System Administration Console introduction . . . . . . . . . . . . . . . . . . . 1060
System category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061
BMC Remedy AR System configuration files . . . . . . . . . . . . . . . . . . . . . . . . 1064
ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
ar.cfg or ar.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
ardb.cfg or ardb.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
armonitor.cfg or armonitor.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
AR System server components and external utilities . . . . . . . . . . . . . . . . . . 1127
AR System server components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
External utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
Centralized configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144
Backing up and restoring centralized configuration settings . . . . . . . . . . 1145
Centralized configuration system forms . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
Configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
Notifications about changes to centralized configuration settings . . . . . . 1235
Updating configuration settings by using the AR System Configuration
Generic UI form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235
Service failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1237
Monitor service failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239
Service provider states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239
Service failover ranking entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241
Changing the ranking of a service provider . . . . . . . . . . . . . . . . . . . . . . . 1242
Naming conventions for service names . . . . . . . . . . . . . . . . . . . . . . . . . . 1242
Email engine service failover in a server group . . . . . . . . . . . . . . . . . . . . 1243
Security administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246
Creating users, groups, and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1247

Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273

Setting up an authentication alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328
Restrictions when logging in to a BMC Remedy AR System server . . . . 1332
Defining your user base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
Understanding database security issues . . . . . . . . . . . . . . . . . . . . . . . . . 1339
Using audit records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
Setting user preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
Accessing preference forms for centralized preferences . . . . . . . . . . . . . 1345
Restricting preferences from users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345
Configuring clients to use a preference server . . . . . . . . . . . . . . . . . . . . . 1345
Establishing a mandatory preference server . . . . . . . . . . . . . . . . . . . . . . 1346
Behaviors associated with preference server configuration . . . . . . . . . . . 1347
Setting the AR System User Preference form . . . . . . . . . . . . . . . . . . . . . 1348
Setting user preferences in the BMC Remedy Mid Tier . . . . . . . . . . . . . . 1373
Defining business schedules using Business Time . . . . . . . . . . . . . . . . . . . . 1374
Business Time introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
Scheduling a time segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
Using time zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
Business Time 2.0 commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
Using the old Business Time forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
Migrating Workdays and Holidays to the Business Time Segment form . 1409
Enabling alert notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
Alert system architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
Alert Events form introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
Viewing alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412
Deleting unread alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412
Registering users for alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413
Using the alert list in a browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
Using Web services with alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
Assigning requests with the Assignment Engine . . . . . . . . . . . . . . . . . . . . . . 1419
Auto-assignment methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419
Assignment process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1420
Assignment Engine Administration Console introduction . . . . . . . . . . . . . 1421
Assignment Engine forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
Enabling and disabling full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
To enable FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423

To disable FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424

Setting up FTS to search across multiple forms . . . . . . . . . . . . . . . . . . . 1424
Re-indexing considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
Defining a field for FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434
How FTS indexing works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437
Performing searches with FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
FTS index migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
Enabling FTS high availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
FTS Operation types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456
Controlling BMC Remedy AR System through email . . . . . . . . . . . . . . . . . . 1457
BMC Remedy Email Engine terminology . . . . . . . . . . . . . . . . . . . . . . . . . 1458
How BMC Remedy Email Engine works . . . . . . . . . . . . . . . . . . . . . . . . . 1458
Setting up outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464
Setting up incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1520
Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557
Creating and using email templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
Email Engine forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
Setting up the approval process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
Approval Server concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
Defining an approval process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
Defining approval rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
Using the Lunch Scheduler sample application . . . . . . . . . . . . . . . . . . . . 1706
Approval forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
Running the approval utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
Managing the BMC Remedy Single Sign-On administrator console . . . . . . . 1793
Managing realms in BMC Remedy Single Sign-On . . . . . . . . . . . . . . . . . . . 1793
To edit realm details: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
To add a new realm: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
Setting up DSO to synchronize data across multiple AR System servers . . 1796
Distributed operations introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
Distributed operations components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803
Implementing DSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
Distributed operations scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1835
Chained and broadcast distributed transfers . . . . . . . . . . . . . . . . . . . . . . 1843
Distributed Server Administration program . . . . . . . . . . . . . . . . . . . . . . . 1855

Managing request IDs in distributed environments . . . . . . . . . . . . . . . . . 1857

Overwriting all fields in duplicate requests . . . . . . . . . . . . . . . . . . . . . . . . 1859
Capturing server events for workflow or API calls . . . . . . . . . . . . . . . . . . . . . 1859
Understanding the Server Events form . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
How the Server Events form is created . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
Types of events you can record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
Viewing the server changes you recorded . . . . . . . . . . . . . . . . . . . . . . . . 1862
Using server events in workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877
Managing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
Auditing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
Archiving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
File types used in migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912
Integrating and migrating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1914
Importing data into BMC Remedy AR System forms . . . . . . . . . . . . . . . . 1969
Importing and exporting Flashboards objects . . . . . . . . . . . . . . . . . . . . . 1980
Exporting and importing data and definitions . . . . . . . . . . . . . . . . . . . . . . 1981
Using the Request ID to improve performance or security . . . . . . . . . . . . 2006
Understanding the AR System database . . . . . . . . . . . . . . . . . . . . . . . . . 2019
SQL definitions of the data dictionary tables . . . . . . . . . . . . . . . . . . . . . . 2051
Migrating applications and data between AR System servers . . . . . . . . . . . 2052
Migration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2052
Navigating the BMC Remedy Migrator interface . . . . . . . . . . . . . . . . . . . 2063
Setting BMC Remedy Migrator options . . . . . . . . . . . . . . . . . . . . . . . . . . 2096
Performing migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2120
Working with migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169
Using migration reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2180
Enabling social collaboration in BMC Remedy AR System . . . . . . . . . . . . . . 2204
Receiving alerts through Twitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
Configuring RSS feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
Configuring chat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2214
Displaying a BMC Remedy AR System form in a portlet . . . . . . . . . . . . . . . 2236
Required knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236
Tested platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236
Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237
Portlet structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2238
Authentication solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2238

Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240

Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
Developing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
Application development with BMC Remedy Developer Studio . . . . . . . . . . 2244
Determining what your application needs to track . . . . . . . . . . . . . . . . . . 2245
Determining what to track . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
Determining how your application should work . . . . . . . . . . . . . . . . . . . . 2246
Designing effective and more usable applications . . . . . . . . . . . . . . . . . . 2247
Designing the user interface effectively . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
Resources for product design and usability . . . . . . . . . . . . . . . . . . . . . . . 2250
Providing accessibility for users with disabilities . . . . . . . . . . . . . . . . . . . 2251
About the Sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
Navigating the BMC Remedy Developer Studio interface . . . . . . . . . . . . . . . 2252
About BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
Starting and logging on to BMC Remedy Developer Studio . . . . . . . . . . 2255
Using menu options in BMC Remedy Developer Studio . . . . . . . . . . . . . 2257
Event Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
Using buttons and menu bar items to execute active links . . . . . . . . . . . 2261
Modifier keywords for use in workflows . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
Understanding the AR System Navigator . . . . . . . . . . . . . . . . . . . . . . . . . 2265
Working with perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267
Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2272
Working with existing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2274
Finding objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283
Using associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2294
Using working lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
Using the Outline tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
Using the Messages tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
Printing from BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . . 2306
Clearing BMC Remedy Developer Studio cache . . . . . . . . . . . . . . . . . . . 2307
Creating reports for selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2307
BMC Developer Studio frequently asked questions . . . . . . . . . . . . . . . . . 2311
Differences between BMC Remedy Administrator and BMC Remedy
Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
Packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318

Creating packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2319

Saving packing lists as XML import or export command files . . . . . . . . . 2322
Working with applications and packing lists . . . . . . . . . . . . . . . . . . . . . . . 2322
Version control in BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . 2324
Using object reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2327
Using the object modification log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2328
Development modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2337
Defining and managing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2345
Local applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2345
Deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2346
Alternatives for presenting applications to users . . . . . . . . . . . . . . . . . . . 2369
Deleting an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2372
Developing the application interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373
BMC Remedy AR System forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373
BMC Remedy AR System installed forms . . . . . . . . . . . . . . . . . . . . . . . . 2409
Using templates to dynamically present HTML content from a form . . . . 2416
Working with panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2422
Working with tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2458
Working with menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2533
Working with images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2559
Creating and managing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2565
Recommendations while developing applications . . . . . . . . . . . . . . . . . . 2678
Adding graphics to an application with flashboards . . . . . . . . . . . . . . . . . . . 2681
BMC Remedy Flashboards overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2681
Data flow in flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2682
Types of flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2683
Process for creating a flashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2690
Planning a flashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2690
Creating flashboard variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2691
Creating and managing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2696
Adding a flashboard to a BMC Remedy AR System form . . . . . . . . . . . . 2703
Securing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2718
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2718
Access control for a deployable application . . . . . . . . . . . . . . . . . . . . . . . 2718
Granting permission to applications and their objects . . . . . . . . . . . . . . . 2719
Defining workflow to automate processes . . . . . . . . . . . . . . . . . . . . . . . . . . . 2720

Introducing workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2720

Configuring workflow forms and execution options . . . . . . . . . . . . . . . . . 2735
Building qualifications and expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 2748
Specifying workflow actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2806
Workflow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2936
Workflow extras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2946
Mid tier application development guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 2960
Managing resource files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2961
URLs for forms and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2962
Creating login and logout buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2971
Creating customized login pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2973
Using the Object List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2974
Embedding web content in an application through data visualization fields . . .
2976
Browser settings for scripting and ActiveX controls . . . . . . . . . . . . . . . . . 2993
How a view is selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2995
How the locale is established . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2995
Types of browser searches for end users . . . . . . . . . . . . . . . . . . . . . . . . 2996
Setting up the query builder widget for end users . . . . . . . . . . . . . . . . . . 2996
Including parameters in saved or defined searches . . . . . . . . . . . . . . . . . 2999
Creating help for web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3000
Adding approvals to an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3001
Designing an approval application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3001
Integrating Approval Server with an application . . . . . . . . . . . . . . . . . . . . 3002
Adding notifications to the approval process . . . . . . . . . . . . . . . . . . . . . . 3008
Creating notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3009
Enhancing your approval forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3018
Adding previews to your approval application . . . . . . . . . . . . . . . . . . . . . 3021
Using the multi-process preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3023
Using a custom ad hoc dialog box with the approval server . . . . . . . . . . 3024
Calling Approval Server application commands in your application . . . . . 3025
Building performance into applications and workflow . . . . . . . . . . . . . . . . . . 3028
Customizing applications using overlays and custom objects . . . . . . . . . . . . 3031
About origin objects and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . 3032
About overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3033
Creating custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3048

Creating overlays to customize objects . . . . . . . . . . . . . . . . . . . . . . . . . . 3049

Working with overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . . 3059
Hiding unmodified objects in Best Practice Customization mode . . . . . . 3078
Converting custom objects to origin objects . . . . . . . . . . . . . . . . . . . . . . . 3079
Converting origin objects to custom objects . . . . . . . . . . . . . . . . . . . . . . . 3081
About export and import operations on overlays and custom objects . . . 3082
About auditing and archiving overlays and custom objects . . . . . . . . . . . 3083
Comparing and reconciling objects using objects list . . . . . . . . . . . . . . . . 3086
Customizing the interface for multiple consumers . . . . . . . . . . . . . . . . . . . . . 3090
Customizing applications with Cascading Style Sheets . . . . . . . . . . . . . . 3091
Customizing views for forms in browsers . . . . . . . . . . . . . . . . . . . . . . . . . 3107
Defining and managing form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3114
Customizing the home page and entry points . . . . . . . . . . . . . . . . . . . . . 3153
Localizing an application to other languages . . . . . . . . . . . . . . . . . . . . . . . . 3180
Localizing BMC Remedy AR System applications . . . . . . . . . . . . . . . . . . 3181
Using the localization toolkit to localize your applications . . . . . . . . . . . . 3201
Making your application accessible - Section 508 compatibility . . . . . . . . . . 3228
What Section 508 support means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3229
Setting accessibility options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3229
Accessibility features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3230
Section 508 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3230
Web settings to support Section 508 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3231
JAWS settings for the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233
Low Vision users and BMC Remedy AR System clients . . . . . . . . . . . . . 3236
No Vision support for BMC Remedy AR System features . . . . . . . . . . . . 3236
Shortcut keys for BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . 3249
Executing active links on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3251
BMC Remedy Mid Tier and caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3251
BMC Remedy Mid Tier and RTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3252
Form design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3252
Verifying your BMC Remedy AR System forms . . . . . . . . . . . . . . . . . . . . 3255
Section 508 rules for application designers . . . . . . . . . . . . . . . . . . . . . . . 3255
Section 508 rules for others . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3263
Testing and debugging a BMC Remedy AR System application . . . . . . . . . 3264
Application debugging process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3264
Debugging tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267

Active link debugging example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267

The BMC Remedy AR System workflow debugger . . . . . . . . . . . . . . . . . 3268
Using Analyzer to find problems in your applications . . . . . . . . . . . . . . . . 3278
Working with the Analyzer View tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3293
Launching the Analyzer from a command line . . . . . . . . . . . . . . . . . . . . . 3296
Capturing application performance with the Mid-Tier Profiler . . . . . . . . . 3302
HTTP tracing in the mid tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3303
Measuring BMC Remedy AR System application performance . . . . . . . . 3304
Moving to production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3401
Importing and exporting object definitions and locking objects . . . . . . . . 3401
BMC Remedy AR System definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3401
Exporting and importing definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3403
Distributing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3418
Locking objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3418
Making applications licensable for integration system vendors . . . . . . . . 3424
Publishing the BMC Remedy AR System functionality as a web service . . . 3430
AR System and web services introduction . . . . . . . . . . . . . . . . . . . . . . . . 3431
Web service standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3432
Predefined BMC Remedy AR System web services . . . . . . . . . . . . . . . . 3434
Forms and field mappings for web services . . . . . . . . . . . . . . . . . . . . . . . 3434
Basic and custom web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3435
Creating web service clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3436
Setting up the environment for web services . . . . . . . . . . . . . . . . . . . . . . 3440
Publishing a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3444
Registering a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3451
Consuming a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3460
Mapping web service data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3467
Using join forms in web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3477
Web service operation types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3478
Web service scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3485
XML editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3513
Supported schema constructs and web service limitations . . . . . . . . . . . 3522
SOAP headers and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3525
Developing an API program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3533
API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3534
When to use API programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3535

BMC Remedy AR System REST API overview . . . . . . . . . . . . . . . . . . . . . . 3535

Understanding JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3536
Tools for testing the REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3539
Login information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3541
Operations on entry objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3543
API use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3561
Configuring the REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3564
General REST API guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3567
BMC Remedy AR System C API overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3568
Client-server application model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3568
BMC Remedy AR System API library functions . . . . . . . . . . . . . . . . . . . . 3569
BMC Remedy AR System C API program structure . . . . . . . . . . . . . . . . 3570
Multithreaded API clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3571
Using the BMC Remedy AR System API for integration . . . . . . . . . . . . . 3572
BMC Remedy AR System API issues and considerations . . . . . . . . . . . . 3574
BMC Remedy AR System C API installation and compilation requirements 3574
BMC Remedy AR System C API package contents . . . . . . . . . . . . . . . . 3574
Migrating to the current release of BMC Remedy AR System C API . . . . 3579
Compile and link requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3582
Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3586
Data relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3586
C data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3587
Lists and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3588
High-level object relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3589
Login and session information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3591
Status information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3593
Permissions and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3595
Group information and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3596
Structures for ARGetListEntryWithMultiSchemaFields . . . . . . . . . . . . . . 3616
Filters, escalations, and active links and structures . . . . . . . . . . . . . . . . . 3632
Character menus and data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . 3647
Images and data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3649
Containers and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3649
Overlays and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3655
Server object properties and structures . . . . . . . . . . . . . . . . . . . . . . . . . . 3656
Importing and exporting and structures . . . . . . . . . . . . . . . . . . . . . . . . . . 3660

Freeing allocated memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3662

XML formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3664
BMC Remedy AR System C API functions . . . . . . . . . . . . . . . . . . . . . . . . . . 3665
Types of functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3665
Function descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3671
Creating and executing BMC Remedy AR System C API programs . . . . . . 4087
Program structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4088
Performing common tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4089
Specifying fields or keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4093
Error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4094
Executing C API programs in workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 4095
Program design tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4096
Multithreaded C API clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4097
Impersonating a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4097
Enabling client-managed transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4098
Sending alerts to a filter API plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4099
Debugging API programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4100
Logging BMC Remedy AR System activity . . . . . . . . . . . . . . . . . . . . . . . 4100
Using the driver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4100
BMC Remedy AR System plug-in API functions . . . . . . . . . . . . . . . . . . . . . . 4106
AR System plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4106
AREA plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4112
ARDBC plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4117
AR Filter API plug-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4135
XML transformation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4136
Transforming XML and BMC Remedy AR System objects . . . . . . . . . . . 4136
Object API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4137
Using the object XML functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4139
Object API function descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4141
Retrieving entries from multiple forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4230
About ARGetListEntryWithMultiSchemaFields . . . . . . . . . . . . . . . . . . . . . 4230
Dynamic joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4236
Recursive queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4239
Value set queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4245
Vendor form joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4251
BMC Remedy AR System Java API overview . . . . . . . . . . . . . . . . . . . . . . . 4253

BMC Remedy AR System Java API installed files . . . . . . . . . . . . . . . . . . 4253

Runtime configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4255
BMC Remedy AR System Java API programming model . . . . . . . . . . . . 4256
Programming with the Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4257
Java API sample code for managing BMC Remedy AR System records 4260
Configuring transformation plugin for Remedy Single Sign-On . . . . . . . . 4264
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4270
Troubleshooting BMC Remedy AR System installation, migration, or upgrade . .
4271
Free and available ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4272
Server issues on DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4272
BMC Remedy Approval Server installation and upgrade issues . . . . . . . 4273
Locating BMC Remedy AR System files and forms . . . . . . . . . . . . . . . . . 4273
Troubleshooting BMC Remedy Migrator installation . . . . . . . . . . . . . . . . 4281
Installation issues on an Oracle database . . . . . . . . . . . . . . . . . . . . . . . . 4281
Understanding digital signatures for Windows installers . . . . . . . . . . . . . 4281
Gathering information for support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4282
Collecting AR System server information . . . . . . . . . . . . . . . . . . . . . . . . . 4282
Collecting Mid tier information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4282
Collecting BMC Remedy Email Engine information . . . . . . . . . . . . . . . . . 4283
Collecting BMC Remedy Assignment Engine information . . . . . . . . . . . . 4283
Collecting BMC Remedy Approval Server information . . . . . . . . . . . . . . . 4283
Collecting Data Import Tool information . . . . . . . . . . . . . . . . . . . . . . . . . . 4284
Collecting BMC Atrium CMDB information . . . . . . . . . . . . . . . . . . . . . . . . 4284
Collecting diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4285
Collecting diagnostics in a zip file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4285
Displaying version information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4287
Checking the database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4287
Creating flashboards to collect server statistics . . . . . . . . . . . . . . . . . . . . 4293
Tracking cache loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4298
Working with logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4308
BMC Remedy AR System Maintenance tool . . . . . . . . . . . . . . . . . . . . . . 4308
Enabling logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4310
BMC Remedy Mid Tier preload logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4363
Logging and monitoring AR System server . . . . . . . . . . . . . . . . . . . . . . . 4364
Viewing logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4365

Using log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4373

Analyzing logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4373
Additional troubleshooting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4423
Working with error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4423
AR System message ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4424
BMC Remedy Migrator error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 4425
BMC Remedy AR System diagnostic messages . . . . . . . . . . . . . . . . . . . 4444
BMC Remedy AR System error messages . . . . . . . . . . . . . . . . . . . . . . . 4448
Running a Health Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4639
To run a Health Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4640
Troubleshooting BMC Remedy AR System performance issues . . . . . . . . . 4641
Peak use issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4644
Hardware issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4644
Memory configuration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4645
Multithreaded server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4645
Checking log files for long-running operations . . . . . . . . . . . . . . . . . . . . . 4647
Troubleshooting server processes on Windows . . . . . . . . . . . . . . . . . . . . . . 4647
Troubleshooting BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4647
Troubleshooting out-of-memory exceptions in the BMC Remedy Mid Tier 4648
Resolving attachment issues in BMC Remedy Mid Tier . . . . . . . . . . . . . 4650
BMC Remedy Mid Tier troubleshooting tips . . . . . . . . . . . . . . . . . . . . . . . 4651
Monitoring mid tier response time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4652
To enable mid tier response time monitoring . . . . . . . . . . . . . . . . . . . . . . 4652
To view overall response time details . . . . . . . . . . . . . . . . . . . . . . . . . . . 4653
Overall response time parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4654
Troubleshooting BMC Remedy Developer Studio issues . . . . . . . . . . . . . . . 4655
Q: When I use a preference server, why are some preferences still stored
locally? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4655
Q: Sometimes, menu commands in the Form, Layout, and Workflow menus
are not available (disabled). How do I make them available? . . . . . . . . . 4655
Q: The tabs in my perspective are not where I want them or I can't find them.
How I do fix the perspective? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4655
Q: When I try to start BMC Remedy Developer Studio, it reports that my
workspace is locked. How can I unlock my workspace? . . . . . . . . . . . . . 4655
Q: Where are all the preferences from the Preferences dialog box of BMC
Remedy Administrator? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4656

Troubleshooting BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . 4657

Troubleshooting BMC Remedy Flashboards displays . . . . . . . . . . . . . . . 4657
Using the FBImageServlet to test a flashboard . . . . . . . . . . . . . . . . . . . . 4660
Troubleshooting BMC Remedy Email Engine . . . . . . . . . . . . . . . . . . . . . . . . 4661
Troubleshooting outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4661
Temporary directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4661
Recommendations for avoiding outages . . . . . . . . . . . . . . . . . . . . . . . . . 4663
Fixing common problems with the BMC Remedy Email Engine . . . . . . . 4663
Configuring mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4663
Defining a heap size for the BMC Remedy Email Engine . . . . . . . . . . . . 4665
Troubleshooting startup issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4666
Determining problems with the mail server . . . . . . . . . . . . . . . . . . . . . . . 4669
Email daemon issues when AR System server stops . . . . . . . . . . . . . . . 4672
Making changes to mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . 4672
Submitting email requests across different time zones . . . . . . . . . . . . . . 4673
Verifying permissions for the Windows accounts . . . . . . . . . . . . . . . . . . . 4673
Troubleshooting email request processing and notification filters . . . . . . 4674
Fixing issues with notifications that fail . . . . . . . . . . . . . . . . . . . . . . . . . . . 4675
Temporary directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4675
Troubleshooting BMC Remedy Approval Server . . . . . . . . . . . . . . . . . . . . . 4676
BMC Remedy Approval Server configuration file settings . . . . . . . . . . . . 4676
Accessibility issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4678
Error 333 and Assignee Group Permission . . . . . . . . . . . . . . . . . . . . . . . 4678
Runtime issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4678
Common error messages for BMC Remedy Approval Server and BMC
Remedy Assignment Engine signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . 4679
BMC Remedy Approval Server files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4681
Troubleshooting BMC Remedy Assignment Engine . . . . . . . . . . . . . . . . . . . 4682
BMC Remedy Assignment Engine files . . . . . . . . . . . . . . . . . . . . . . . . . . 4682
Troubleshooting BMC Remedy Distributed Server Option . . . . . . . . . . . . . . 4683
Errors encountered by Distributed Server Option . . . . . . . . . . . . . . . . . . 4683
BMC Remedy Distributed Server Option files . . . . . . . . . . . . . . . . . . . . . 4684
Verifying the Distributed Server Option is in active state . . . . . . . . . . . . . 4685
Missing distributed operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4686
Performance issues processing Distributed Server Option operations . . 4687
Verifying the Distributed Server Option is in active state 9.1 . . . . . . . . . . 4687

Troubleshooting full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4689

To enable FTS index logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4689
To enable SQL logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4690
Cannot connect to the Java plug-in server . . . . . . . . . . . . . . . . . . . . . . . . 4690
Troubleshooting plug-in issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4690
General approach for troubleshooting plug-in issues . . . . . . . . . . . . . . . . 4691
Enabling server-side AR System logs . . . . . . . . . . . . . . . . . . . . . . . . . . . 4692
Troubleshooting issues with plug-in servers . . . . . . . . . . . . . . . . . . . . . . 4694
Troubleshooting issues with ARDBC plug-ins . . . . . . . . . . . . . . . . . . . . . 4698
Troubleshooting issues with AR System Filter API plug-ins . . . . . . . . . . . 4715
Troubleshooting issues with AREA plug-ins . . . . . . . . . . . . . . . . . . . . . . . 4747
Troubleshooting encryption security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4751
Java-based encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4751
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4751
Troubleshooting BMC Remedy SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . . 4751
Troubleshooting issues with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . 4753
Troubleshooting alert activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4754
Using alerts in a server group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4754
Checking the status of alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4754
Using alert and Web service logs to check alert activity . . . . . . . . . . . . . 4754
Searching the Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4755
To search the Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4755
Troubleshooting issues connecting to the AR System server . . . . . . . . . . . . 4755
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4756
Running arconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4756
Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4761
Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4761
Support status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4761
Troubleshooting BMC Remedy Single Sign-On issues . . . . . . . . . . . . . . . . . 4761
Troubleshooting BMC Remedy Single Sign-On log on and log off issues 4761
Manually integrating BMC Remedy Single Sign-On with BMC Remedy
applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4764
Troubleshooting BMC Remedy Single Sign-On integration issues . . . . . 4768
Troubleshooting authentication issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 4773
Common errors and issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4775
Handling logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4776

Troubleshooting AR 623 error during integration . . . . . . . . . . . . . . . . . . . 4777

FAQs and additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4779
Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4779
BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4779
PDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4781
Additional resources from BMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4781
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4782

This space contains information about the 9.1 release of the BMC Remedy Action Request System
(BMC Remedy AR System), BMC Remedy Encryption Security, and BMC Remedy Migrator
products, including service packs and patches. BMC Remedy Action Request System enables you
to automate many business processes without learning a programming language or complex
development tools.
Release notes and notices (see page 30)
Getting started (see page 57)
Planning (see page 183)

Installing (see page 238)
Upgrading (see page 710)
Troubleshooting (see page 4270)
Using (see page 901)
Administering (see page 1059)
Integrating (see page 713)
FAQs and additional resources (see page 4779)

PDFs and videos
Announcements
BMC Remedy Action Request System 9.1 is available with the following new features:
Enhancements to Centralized configuration

BMC Remedy Deployment Application enhancements
Improved search relevancy for Multi-Form Search (MFS)
Enhancements to armonitor
For the details, see 9.1.00 enhancements (see page 46).

Release notes and notices

This section provides information about what is new or changed in this space, including resolved
issues, documentation updates, maintenance releases, service packs, and patches. It also
provides license entitlement information for the release.
Tip
To stay informed of changes to this space, place a watch on this page.
The following interactive graphic summarizes enhancements for the BMC Remedy Action Request
System 9.1. (The graphic may take a few seconds to load).
Click here to view interactive diagram online
The following updates have been added since the release of the space:

Date Title Summary
December 22, 9.1.00 enhancements (see BMC Remedy AR System 9.1 has been enhanced with the following new
2015 page 46) features and changes:
Enhancements to Centralized configuration

BMC Remedy Deployment Application enhancements
Enhancements to armonitor file
Related topics:
Known and corrected issues (see page 31)
Support information (see page 4761)
Known and corrected issues

Use this section to:
Learn about the issues that are corrected in the 9.1 release and in its subsequent service
packs and patches.
Look for open issues and workarounds to known problems before contacting BMC
Customer Support.
For known and corrected issues related to installation and upgrades, see Platform (AR
System and CMDB) installation and upgrade known and corrected issues
Tip
The known and corrected issues table includes the Component, Issue, Description,
Affected versions, and Corrected in columns. If you cannot view all the columns, click
the icon on the top-right corner of the page to open it in full screen mode.
Alternatively, use the scroll bar at the bottom of the table.
The following issues pertain to this release of BMC Remedy AR System and its patches. To locate
known and corrected issues, perform any of the following actions:
Select an option from the Corrected in list to filter the table by version number. An issue
with no version number listed here remains open. A workaround is provided, if available.

Select an option from the Category list to filter the table by a specific component, such as
AR System Server or Developer Studio.
Type a character string in one or more of the boxes to filter the list of defects.
Click any column heading to sort this table or change sort direction.
Component Issue Description Affected

versions
AR System SW00491125 MultiForm Search or Global Search generates the following exception when the 9.1.00,
server search string contains brackets within double quotes
9.0.01
Unknown system error : java.lang.StackOverflowError (ARERR
8790)
AR System SW00491979 In case of termination due to manual shut-down, server restart, or server logout on 9.1.00,
server Windows 2008 or Windows 7 the DDM fails to store the last migrated record ID in the
9.0.01
<instruction_file>_LastSuccessfulID.txt file present in a Working folder under
<MigratorInstallDirectory>\DeltaDataMigration. The CTRL_SHUTDOWN_EVENT
and CTRL_LOGOFF_EVENT are not received on Windows 2008 or Windows 7
which causes the failure.
AR System SW00492765 When you modify a value for a CI using a Russian locale and retrieve the value using 9.1.00
server ARGetEntry API call, the AR API returns garbage characters.
AR System SW00492280 If you select a non-English locale and perform a message action on a filter or active 9.1.00
server link, the field id in the message are not replaced with the field values.
AR System SW00494143 If you use Oracle database and BMC Remedy Knowledge Management's external 9.1.00,
server file system knowledge source, and when schema reindex or periodic scan is
9.0.01
performed for RKM:VF_FileSystem vendor form, the following error occurs in
arerror.log file:
ORA-01652: unable to extend temp segment by 128 in tablespace

ARTMPSPC_8000
Workaround:
Prerequisites
1. If you are using Oracle database and BMC Remedy IT Service Management
is already installed before upgrading to BMC Remedy AR System 9. 0 Service
Pack 1, or,
2. If you are using Oracle database and BMC Remedy IT Service Management
is freshly installed, after fresh installation of BMC Remedy IT Service
Management is complete.
Perform the following steps:
1. Identify the schema id for RKM:VF_FileSystem vendor form using following

SQL query:
SELECT schemaId, name FROM arschema WHERE name = 'RKM:
VF_FileSystem';
2. Create an index on E0, E1 … E31 columns on B table for above form to allow
Oracle to generate appropriate index for dynamic data in this vendor form
using the following SQL query:
CREATE INDEX INDEX_E32_B<schema-id> ON B<schema-id> (E0,


versions
E1, E2, E3, E4, E5, E6, E7, E8, E9, E10, E11, E12, E13,
E14, E15, E16, E17, E18, E19, E20, E21, E22, E23, E24,
E25, E26, E27, E28, E29, E30, E31);
COMMIT;
where, <schema-id> is the schemaId received from the above query.
AR System SW00417387 An email message is sent to all the users registered on the People form 9.1.00,
server (users belonging to a particular group) under either of the following circumstances:
9.0.00,
A user on the People form has an email address such as "00000",
8.1.00,
group IDs, or some garbage characters, and an incident is created for this
user. 7.6.04,
The user who is creating a ticket for the customer for whom the incident is
being created 7.5.00,
replaces the value in the Email address field with zeros (for example, 000000)
7.1.00
or the group ID and submits the incident.
AR System SW00493589 When C API client tries to connect to BMC Remedy AR System 9.0 Service Pack 1 9.0.01
server on Internet Protocol version 6 (IPv6) using a port mapper, the connection fails with
the following error:
Cannot establish a network connection to the AR System server.
Workaround:
Install BMC Remedy AR System 9.0 Service Pack 1 on Internet Protocol version 6
(IPv6).
AR System SW00445408 If you integrate BMC Remedy AR System and BMC Atrium Single Sign-On in version 9.0.00,
server 8.0.00
8.1.00,
and then you upgrade the BMC Remedy AR System server and
BMC Remedy Mid Tier to version 9.0, you break the integration with the SSO Server.
8.0.00
Workaround:
Re-run the version 9.0 SSO integration utilities that are installed with the
BMC Remedy AR System server and BMC Remedy Mid Tier to restore the
integration with the version 8.0.00 SSO Server.
For more information, see:
Running SSOARIntegration utility on the AR System server

Running the SSOMidtierIntegration utility on the Mid Tier
Note: BMC recommends that you upgrade BMC Atrium Single Sign-On to
version 9.0 as well.
AR System SW00467043 In the AR System Job form, when you create a job with Job Type as Report and 9.1.00,
server select
9.0.00,
Schedule Information type as Hourly or By Minute,the record is not created
generating the following error: 8.1.00
ARERR [8753] Error in plugin: ARSYS.ARF.REPORTSCHEDULER
Workaround:
For the Schedule Information type as Hourly, manually set the recurrence field.
For example:


versions
weekofmonth=;dayofmonth=;weekdays=0-6;frequency=1;subtype=;hours=0-23;
AR System SW00467816 In BMC Remedy AR System 9.0, when you create a web service filter action and 9.1.00,
server specify
the username in the format <domainName\username>, the domainName is removed 9.0.00,
automatically. 8.1.01
The web service filter action fails and a 401 Unauthorized Error error occurs.
Workaround:
Specify the username in the format <domainName\domainName\username> or
<username@FullyQualifiedDomainName>.
For example if the domainName is abc and username is xyz, specify the username
in the format abc\abc\xyz or xyz@abc.com
AR System SW00469288 In BMC Remedy AR System 9.0 on a Windows Operating System with HR (Croatian) 9.1.00,
server locale,
9.0.00,
the AR Server converts the dates to dd.mm.yyyy HH:MM:SS format,
but it does not convert the date back to EPOCH format. The following error occurs: 8.1.01
ARERR 313: Incompatible data types for intended relational
operation.
AR System SW00488782 The BMC Remedy AR System 9.1 does not support the data type LONG RAW. 9.1.00,
server
After upgrading to BMC Remedy AR System 9.1, when you insert data into the 9.0.01,
character fields,
9.0.00
diary fields or attachment fields which have data type as LONG RAW, and you
search for the data,
the data is not displayed in the search results.
Workaround:
Execute the following commands to search for all the columns that use the data type
as LONG RAW
and convert the data type for these columns to BLOB or CLOB.
For Character and Diary fields:
1. a. Execute the following command to find the columns which have data
type as LONG RAW:
SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE FROM

ALL_TAB_COLUMNS
WHERE DATA_TYPE='LONG RAW' AND
(TABLE_NAME IN (SELECT CONCAT('T', SCHEMAID) from arschema))
b. Execute the following command for each entry obtained from the above
query to
convert the data type to CLOB
ALTER TABLE <tableName> MODIFY (<columnName> CLOB);
For Attachment fields:
1. a. Execute the following command to find the columns which have data
type as LONG RAW:

1. a.

versions
SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE FROM

ALL_TAB_COLUMNS
WHERE DATA_TYPE='LONG RAW' AND TABLE_NAME LIKE 'B%'
AND COLUMN_NAME LIKE 'C%'
b. Execute the following command for each entry obtained from the above
query
to convert the data type to BLOB
ALTER TABLE tableName MODIFY ( columnName BLOB);
AR System SW00471581 If you upgrade from BMC Remedy IT Service Management 7.6.04 or an earlier 9.1.00,
server version to 9.1,
9.0.00,
there is a potential for view creation failure during the upgrade resulting in a field
count mismatch on forms. 8.1.01
These forms are not cached when you restart the AR Server.
AR System SW00487839 BMC Atrium Integrator data is not available on the AR System Server Group 9.1.00,
server Operation Ranking form.
9.0.01,
Workaround:
9.0.00
Perform the following steps to add the data manually:
1. Open the AR System Server Group Operation Ranking form in New

Request mode.
2. Select Atrium Integrator from Operations list.
3. From the Server list, select the server name.
4. Add rank and click Save.
AR System SW00488374 If you register RKM External File Source to BMC Knowledge Management and 9.1.00,
server upgrade to
9.0.01,
BMC Remedy IT Service Management version 9.0, duplicate Knowledge Articles are
created. 9.0.00
Workaround:
1. Open the RKM:VF_FileSystem_Manageable_Join form in BMC Remedy

Developer Studio.
2. From the Definitions tab, select Full TextSearch link.
3. In the Days field enter 5 and save the form.
4. Upgrade the BMC Remedy AR System server.
If the issue still persists, perform the following steps:
1. Login to BMC Remedy AR System server as a Knowledge Management

Administrator.
2. Select Application > Knowledge Management > Knowledge Management
Console.
3. From the Functions tab, select Manage Knowledge Sources.
4. From the pop up window select the sources which are of the type File System
Path and
click Rebuild Index.


versions
Note: The Rebuild requires time based on the number of files registered as File
System Path Source.
AR System SW00494703 If you enable the Always Logging ON with default settings, the Java plugin server 9.1.00
server heap memory consumption is high.
SW00498954
Workaround:
1. Open the armonitor configuration file. For Windows, armonitor.cfg file located
at <ARSystemInstallDir>\ARSystem\Arserver\Conf folder. For UNIX,
armonitor.conf located at /etc/arsystem/serverName folder.
2. Locate the Java plug-in server command and add the following parameters:
-XX:+UseConcMarkSweepGC
-XX:+UseParNewGC
For example:
"C:\Program Files\Java\jre1.8.0_51\bin\java" -Xmx512m -classpath -XX:

+UseConcMarkSweepGC -XX:+UseParNewGC
"C:\Program Files\BMC Software\ARSystem\pluginsvr;
C:\Program Files\BMC Software\ARSystem\pluginsvr\arpluginsvr91_build001.
jar;
C:\Program Files\BMC
Software\ARSystem\approval\bin\armaskingImpl91_build001.jar;
C:\Program Files\BMC
Software\ARSystem\arserver\api\lib\arcmnapp91_build001.jar" com.bmc.arsys.
pluginsvr.ARPluginServerMain -x <SERVER NAME> -i "C:\Program Files\BMC
Software\ARSystem
AR System SW00496301 If you use the following query on BMC Remedy AR System server with Oracle 12 9.1.00
server database:
select DATEDIFF('dd',DateAdd('dd',6,`Modified Date`),DATEADD('dd',4321,

`Create Date`)) as D1,
DATEDIFF('wk',DateAdd('dd',6,`Modified Date`),DATEADD('dd',4321,`Create
Date`)) as D2
from `JDBCTestFormA`
you might get the following error: Error: ERROR (552): The SQL database operation
failed.; ORA-00918: column ambiguously defined This error occurs due to the
limitations in Oracle 12 to execute such type of queries.
AR System SW00498432 If you export the User form data and import back, from an old client (for example 9.1.00
server BMC Remedy Mid Tier 9.0 SP1 or BMC Remedy Mid Tier 8.1) which is connected to
SW00499897 BMC Remedy AR System server 9.1, authentication fails.
The login fails due to the change in password storage format. When you login to
BMC Remedy AR System server 9.1, the password is stored in a new format.
However the older clients use the old client libraries to export data and assume that
the password is in old format, and we cannot export the User form data and import
back.
Workaround:
You should use the clients upgraded to 9.1 to export and import data.
SW00497005 9.1.00


versions
AR System If you execute a SQL query on database then the Except operator takes precedence
server over the other operators. For a JDBC query, the query traversal is from left to right
irrespective of the Set operator. So the results for such queries differ.
AR System SW00498437 If you execute JDBC set queries having different alias names, the query is not 9.1.00
server parsed and you might get an error message.
Workaround:
You should use the same alias name for set query.
AR System SW00495468 If you are using an Oracle database and you use a JDBC query with the LPAD and 9.1.00
server RPAD functions, the following error occurs:
Error: ERROR (552): The SQL database operation failed.; ORA-00932: inconsistent
datatypes: expected CHAR got NUMBER The LPAD and RPAD functionality is
supported for character fields only and not supported for integer fields.
BMC SW00494010 After max session time on BMC Remedy Single Sign-On is reached and session is 9.1.00,
Remedy terminated, the user is not redirected to the login screen immediately resulting in
9.0.01
Single Sign- error messages 623 thrown at user every action.
On
Workaround
Close the browser and log on again in a new window.
BMC SW00494024 The memory size consumed by BMC Remedy Single Sign-On Tomcat process 9.1.00
Remedy keeps growing and eventually triggers the Linux OOM killer to kill the process.
Single Sign-
On
BMC SW00497209 While manually configuring BMC Remedy Single Sign-On, when the user uses a 9.1.00
Remedy "plain text password" as the DB password, the user is not able to log on.
Single Sign-
On Workaround
The user must use the rsso-ds.jar utility to generate an AES-encrypted password.
Usage: java -jar [encryption-algorithm] [initial-key]
Example:
Usage: java -jar rsso-ds.jar my_db_password aes my_key_to_encode
The user must then update the password in the database.properties file.
BMC SW00500279 In the BMC Remedy Single Sign-On Admin console, the user can create unlimited 9.1.00
Remedy number of realms with the same Realm ID.
Single Sign-
On Workaround
Delete the duplicate realms one by one from the user interface and re-create them
using different realm IDs.
Approval SW00496454/ In Approval Central console, you are unable to approve service requests by clicking 9.1.00
Server SW00497035 Approve. The requests are moved back to Pending state.
Approval SW00494125 In Approval Server, if approval engine fails to release the lock when uncaught 9.0.01
Server exception occurs during custom approval process, the Approval Server stops
responding and cannot clear the pending application.


versions
Developer SW00436945 When you upgrade to version 9.0, the existing overlay objects display the overlay 9.1.00,
Studio type as
9.0.00,
No Overlay for the granular sections such as Permissions, Indexes, Other
Definitions, and so forth. 8.1.00,
Workaround: 8.0.00
Create a new workspace while launching BMC Remedy Developer Studio. The
overlay objects show the overlay type as Overwrite.
Note: The overlay type for Indexes is displayed as Additive.
Developer SW00475891 When you create an association between the main form and its audit form and you 9.1.00,
Studio have chosen this
9.0.00
to follow this association during archiving, all the related audit entries are also
archived with that form.
However, after archiving, when you delete the archived records from the main form,
an audit entry gets added for deletion in the audit form and it is not archived.
Workaround:
you can choose to archive those entries in your audit form which were created due to
deletion
on the form by archive user.
1. Define an archive on your audit form.

2. Select Appear in Archive Policy check box.
3. Add the qualification as 'User'='AR_ARCHIVER' & 'Action'='Delete'.
4. Save the form.
Developer SW00498567 When you open the Developer Studio in Base mode, a banner is displayed in yellow 9.1.00
Studio color. If you try to resize this banner, the resizing fails.
Workaround:
To hide the banner, click Hide.

To restore the banner to its normal size, reset the perspective or navigate to
Window > Show view > Other... > BMC Developer Studio and select Mode
Info.
Email SW00359899 Because the BMC Remedy Email Engine has an open issue for supporting 9.1.00,
Engine LDAP user authentication, the approval notification through the email
9.0.00,
feature is currently not available for users residing on LDAP directories.
8.1.00,
8.0.00,
7.6.03
Mid Tier SW00482947 The fields on the Home page navigation bar for all the BMC Remedy IT Service 9.1.00
Management applications do not gain focus even after you access them using
Keyboard.
Mid Tier SW00492953 In Mozilla Firefox, if you select a Chinese locale in the User Locale list on the Locale 9.1.00,
tab in the AR System User Preference form, the field value on the User form is not
9.0.01
displayed properly.


versions
Mid Tier SW00464462 When you create a new incident by using the Incident Management Console, 9.1.00,
if you select a value from a drop-down list or enter multiple characters in a character
9.0.00,
field,
8.1.00
the new screen rendition is delayed. This delay happens when the chat status in
Incident Management Console is Online.
If you change the chat status to Offline, there is no delay in screen rendition.
This issue is observed in Mozilla Firefox 23, Internet Explorer 8 or other browsers.
Mid Tier SW00475922 The Sync Cache operation does not rebuild the image if you make any changes to 9.1.00,
the image.
9.0.00
Also deleting the image during Sync Cache operation, results in a heavy
performance hit in mid tier.
Workaround:
Change the image name, update the form where the image is saved and
then perform the Sync Cache operation to reflect the changes on mid tier.
Mid Tier SW00434214 When you click a bookmark, the link does not point to the exact bookmark location, 9.1.00,
so you cannot identify the bookmark text in an article.
9.0.00,
8.1.00,
8.0.01
Mid Tier SW00440761 After you run the Atrium SSO Integration Utility for AR System version 9.1 and 9.1.00,
BMC Atrium Single Sign-On version 9.1 with JBoss 6, the JBoss logs
9.0.00,
contain an exception. As a result, the mid tier URL returns the following error:
The requested resource (/arsys) is not available. 8.1.00,
Workaround: 8.0.01
1. Remove the Doctype element from web.xml.

For example:
<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD
Web Application 2.3//EN' 'http://java.sun.com/dtd/web-
app_2_3.dtd'>
2. Replace the <web-app> element with a new one. Do not enter extra spaces.
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
3. Remove all the <display-name> tags from web.xml.

4. Replace the birt tag element <taglib> with a new one.
Previous tag:
<taglib>
<taglib-uri>/birt.tld
</taglib-uri>
<taglib-location>
/WEB-INF/tlds/birt.tld
</taglib-location>
</taglib>


versions
New tag:
<jsp-config>
<taglib>
<taglib-uri>http://www.eclipse.org/birt/taglibs/birt.tld
</taglib-uri>
<taglib-location>/WEB-INF/tlds/birt.tld
</taglib-location>
</taglib>
</jsp-config>
5. Restart Jboss with the -b 0.0.0.0 option.
Mid Tier SW00434732 If you install the BMC Remedy Mid Tier with the AR Crystal Web application on a 9.1.00,
64-bit Windows system with BusinessObjects XI version 4 installed, the mid tier
9.0.00,
creates ODBC-driver information on the system. If you open the
ODBC Administrator Tool from the Windows Control Panel, you will not see the 8.1.00,
BMC Remedy AR System ODBC driver listed.
8.0.01
Workaround:
Open the ODBC Administrator Tool from a command prompt:
<WindowsHomeDirectory>\SysWOW64\odbcad32.exe
Mid Tier SW00431582 If you log on to a central mid tier in a distributed mid tier environment using a Safari 9.0.00,
browser
8.1.00,
and open a remote mid tier on a new Safari browser to display a form that resides on
a remote server,
8.0.00
make some changes, and then you log out from the remote mid tier without saving
the changes,
BMC Remedy Mid Tier does not display a warning that the changes are not saved.
Mid Tier SW00380883 When you open the customizable home page in an inline view field, 9.1.00,
the images to expand or collapse the panels, and to add or remove panels do not
9.0.00,
display correctly.
8.1.00,
Workaround:
8.0.00,
1. Open the AR System Customizable Home Page in BMC Remedy Developer
Studio. 7.6.04
2. Select the Default Administrator View tab and open the Properties window.
3. Go to the Web Header Content property and click the ellipses button.
You see the CSS style rules that reference the class img.btnimg enclosed
in the <STYLE> tag.
4. Open the form with a view field on which you have embedded the home page.
For example, Form X.
5. Verify the <STYLE> tag in the Web Header Content property for Form X.
The CSS rules pertaining to the image buttons must be the same as in AR
System Customizable Home Page.
6. If the style is different, and you are in Best Practice Customization Mode,
create an overlay of the form (Form X). For more information about how to
create an overlay, see Developing an application (see page 2242).
7. Copy the style from the home page form and paste it into the Web Header
Content property
on the form (or the form overlay, as appropriate).
8.

versions
8. If you have other views, or outer parent forms, repeat step 4 through step 7.
For example,assume that you have Form Y with a view field. You embed AR
System Customizable Home Page
on Form Y's view field. The Form Y style for image buttons must match with
the home page style.
Mid Tier SW00380696 Inline view fields do not support Right-to-left (RTL) formatting if the parent form is 9.1.00,
using the Left-to-Right (LTR) mode and vice versa.
9.0.00,
Note: IFrame supports this functionality.
8.1.00,
8.0.00,
7.6.04
Mid Tier SW00342716 If you place a table in a panel, set the panel's Layout Style property to Fill, and set 9.1.00,
the table's
9.0.00,
Auto Fit Columns property to True, the table columns will shrink to fit into the
panel's initial size 8.1.00,
(possibly making the columns unreadable), and the panel is not filled as it grows and
extra slack is left behind. 8.0.00,
7.6.04,
Workaround: Set the table's Auto Fit Columns property to False.
7.6.03
Mid Tier SW00466918 When you upgrade from BMC Remedy Mid Tier 7.6.04 Service Pack 1 to BMC 9.1.00,
Remedy Mid Tier 9.0,
9.0.00,
the user defined values in server.xml file are not retained.
8.1.00,
8.0.00
Mid Tier SW00465528 The following error is displayed in Microsoft Internet Explorer 9 or 10 when the 9.1.00,
value of arsystem.emit_X_UA_compatible_mode variable is set to 10 in the Mid-
9.0.00,
tier configuration file:
ARERR [9506] Unable to display form 8.1.01
Workaround:
Change the browser compatibility settings of the Microsoft Internet Explorer manually.
In Internet Explorer, go to Tools > Compatibility view settings,
and deselect the Display intranet sites in compatibility view option.
Mid Tier SW00464696 The following issues were identified with the Remedy Knowledge Management 9.1.00,
Application (RKM)
9.0.00,
and BMC Remedy Service Request Management forms when using JAWS:
8.1.00
When you open a knowledge entry from the Request Entry form, the dialog
box that
appears is different and does not read the knowledge entry data correctly.
On Service Request forms, all the answer fields are identified as edit fields
regardless of their type.
When you cancel a Service Request form, the confirmation dialog box shows
unwanted string
of text before displaying the message Are you sure.


versions
Mid Tier SW00469539 If you create Web Reports using the BIRT report designer tool, and then import the 9.1.00,
report to
9.0.00,
AR System, and then export the report to MS Excel using Mid Tier,
the heap memory usage rises until either you get an 8.1.01
Out of memory error or you get an Invalid row number error from the BIRT
runtime.
You cannot export the report to MS Excel.
Mid Tier SW00485019 While accessing the applications using BMC Remedy Mid Tier, 9.0.00
you can open multiple browser windows using workflows.
All the forms opened using the workflows are closed after you log out.
But if you make any changes to open the forms (for example, change the URL in
web address bar
or refresh the page or access any other forms by typing form name) or if a new
browser window or
tab is opened and other forms are accessed. Such windows are not closed by the
mid tier after you log out,
but a session timeout error is displayed if you perform any operations on them.
RTF fields SW00363909 When users select multiple table cells in an RTF field, editing operations do not work 9.1.00,
correctly
9.0.00,
in Internet Explorer browsers. For example, users cannot delete text in multiple table
cells in an RTF field; 8.1.00,
they must delete the text in each cell individually.
8.0.00,
7.6.04,
7.6.03
RTF fields SW00363912 In modify mode, dynamic resizing of RTF fields fails when you switch among panels 9.1.00,
(that were initially collapsed) with RTF Auto Resize set to Vertical in a flow layout
panel. 9.0.00,
This issue occurs in all browsers. In create mode, dynamic resizing works for RTF 8.1.00,
fields.
Only the Collapsible and Accordion panels are affected. 8.0.00,
7.6.04,
7.6.03
RTF fields SW00379854 Inline RTF fields are not supported on floating panels. 9.1.00,
Workaround: Use non-inline RTF fields.
9.0.00,
8.1.00,
8.0.00,
7.6.04
RTF fields SW00383294 In an RTF field with an append menu option, irrespective of where the cursor is set, 9.1.00,
the menu value is always added at the end of the text.
9.0.00,
8.1.00,
8.0.00,
7.6.04,


versions
7.6.03
RTF fields SW00415604 The following are the Rich Text Formatting (RTF) fields open issues for the release: 9.1.00,
SW00414089: When you select the text in the RTF editor and press the Delete 9.0.00,
key,
8.1.00,
an empty box appears in the editor.
SW00411835: After adding an Expand section and typing some text in the 8.0.00
RTF editor,
if you expand and close the section on Internet Explorer 9, the text appears
twice for some time
and then the field refreshes. Also, if you expand the section again, the text
might not display for some time.
SW00410112: When you open a form with an RTF field in Internet Explorer 8
and create a table,
if you then use the mouse to select the table, the table is not highlighted to
identify the selection.
On Firefox, the table border changes to light blue to indicate the selection.
SW00414748: After you click the Spell Checker option on the RTF editor,
if you move the RTF editor to the browser borders, the Spell Checker window
moves or appears outside the browser.
SW00414538: When you enable the Show/Hide Hidden Elements option in
an RTF field in Safari 5.0.5
and close the RTF editor, the option is not enabled when you re-open the
editor.
SW00414535: The Spell Checker option is enabled even when there is no
text in the RTF editor.
SW00402639: Even though the font size is 14, on Internet Explorer 8 the text
appears with
font size 10 in the Expand section Header and the text area.
SW00412246: The Line spaces appear small in the RTF fields and the line
space between the lines
differs in the RTF field and RTF editor. Also, the spaces between the text and
line display differently
in edit mode and display mode.
SW00415767: The spell checker removes some special characters on
Internet Explorer 8.
SW00411837: You cannot cut, copy, and paste the RTF field Expand section
easily on Internet Explorer 9.
SW00411557: You must copy the RTF field Expand section precisely on
Firefox to
copy and paste the section, otherwise the section is not pasted correctly.
SW00416496: In Firefox browsers, the spell checker does always not highlight
all instances of misspelled words.
Also, when you click the Spell Checker option for the second time,
sometimes the Spell Checker window
does not display a message about no misspelled words found.
(These issues only occur when you copy and paste from an outside editor
such as Word.)
SW00414056: Sometimes the cursor is automatically set to the second line
when you open an
RTF editor or set focus to an RTF field.
SW00418290: The spell checker deletes the leading white space above the
Expand section in Internet Explorer.


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


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

Flashboards version 9.0.
Install BMC Remedy Flashboards version 9.0 in a different location.
Encryption SW00481606 The BMC Remedy Encryption Performance or BMC Remedy Encryption Premium 9.1.00,
Security installation
9.0.00
is not required on java clients if the AR System server uses RC4 with a 128-bit key
for data encryption.
Migrator SW00436853 When an object's permission is set to Additive overlay and new permissions are 9.0.00,
added to the overlay object, the destination server displays duplicate entries
8.1.00,
for the existing base permissions after migration.
For example, if a Struct Admin permission exists for a base form and you add the 8.0.01
Struct Subadmin permission in the additive overlay, after migration Developer Studio
displays a duplicate entry for Struct Admin as added-in overlay.
Migrator SW00362555 The BMC Remedy Migrator Command Line Interface (CLI) takes a long time to 9.0.00,
generate
8.1.00,
the .migrator file on the BMC Remedy IT Service Management (ITSM) stack.
The size of the .migrator file cannot exceed 2 GB. 7.6.04,
Workaround: Instead of creating the .migrator file for the whole stack, 7.5.00
create it in chunks based on object types.


versions
Migrator SW00412690 Delta Data Migration (DDM) reports the No Activity Currency code found 9.0.00,
message
8.1.00,
in the APR: Approver Lookup and APR:Sys-Approval Definition forms.
7.6.04
Workaround: If there is a difference in data on the following forms,
you do not create or update the forms:
APR:Approver Lookup (approval mappings)

APR:SYS-Approval Definition (approval process definition)
Migrator SW00499968 During migration or comparison, the migrator searches for AP: 9.1.00,
Tooltip_Information_Archive form on the source server and destination server
9.0.01,
using the AR_Archive_Forms.xml file. As the BMC Remedy AR System server
stores the form with name AP:ToolTip_Information_Archive, the migrator returns 9.0.00
the following error:
Form does not exist on server.
Workaround:
Open the AR_Archive_Forms.xml file located at

<MigratorInstallationPath>\DeltaDataMigration\Packages\ARCore\<VERSION>
.
Edit the source form name and destination form name from AP:
Tooltip_Information_Archive to AP:ToolTip_Information_Archive.
9.1.00 enhancements
This topic provides information about the following enhancements in this release:
Centralized configuration available for more parameters (see page 46)

Improved functionality for BMC Remedy Deployment Application (see page 47)
Improved search relevancy for Multi-Form Search (MFS) (see page 47)
Enhancements to armonitor (see page 47)
Centralized configuration available for more parameters

In the 9.1 release, parameters for the following components have been migrated to the centralized
configuration console:
BMC Remedy Distributed Server Option

BMC Remedy Flashboards server
BMC Remedy Assignment Engine
AR System Database Connectivity (ARDBC) LDAP plug-in
AR External Authentication (AREA) LDAP plug-in

Previously, these parameters were stored either in the ar.cfg file or in the server.conf file. Now,
you can make changes to the parameters of these components through the centralized
configuration console. For more information, see Centralized configuration (see page 1144).
Improved functionality for BMC Remedy Deployment

Application
The following enhancements for BMC Remedy Deployment Application are available:
Enhancement Description
Rollback functionality Restores the objects in a package to the pre-deployment state if any issues are found during
validation of the package after the package is deployed successfully. For more information, see
Rollback .
Migration support Transfers BMC Remedy AR System service request definitions (SRDs), process definition
for Service Request templates (PDTs), and supporting data easily and reliably across environments. For more
Management information, see Adding SRM objects to a package .
(SRM) objects

Starting with this release, a new aggregate field is added to the index file for Multi-Form Search.
The aggregate field is a collection of all the fields in the index file and the AR System server
searches on this field to produce better search results.
Enhancements to armonitor
In BMC Remedy Action Request System 9.1, a new Java-based file armonitor is used to maintain
a list of all BMC Remedy AR System processes. The armonitor file provides functionality to detect
changes made to the armonitor.cfg (armonitor.conf) file. The armonitor also provides
enhancement to start, stop, restart, and modify the processes maintained in armonitor.cfg (
armonitor.conf) file. For more information see, armonitor (see page 1127).
Locating white papers, guides, and technical

bulletins
Use the information in the following sections to locate content in the online documentation that was
previously provided in PDF format. In many cases, the content has been distributed among several
sections in the BMC Remedy Action Request (AR) System space, depending on the task being
performed.
BMC Remedy AR System online documentation (see page 48)

BMC Remedy Encryption online documentation (see page 52)
BMC Remedy Migrator online documentation (see page 52)
BMC Remedy IT Service Management Preconfigured Stack online documentation (see
page 53)

White papers online (see page 53)
BMC Remedy AR System online documentation

Document Online section
Release Notes Release notes and notices (see page 30)

BMC Remedy Action Request System known and corrected issues in version 9.0 (see page 31)
C API Reference Developing an API program (see page 3533)
Concepts Guide Key concepts (see page 58)
Configuration Guide Key concepts

BMC Remedy AR System client server architecture (see page 141)
License overview (see page 85)
Configuring after installation

Configuring a Unicode server (see page 511)
Configuring AR System servers (see page 255)
BMC Remedy AR System cache management (see page 369)
Administering
Navigating the BMC Remedy AR System Administration console interface (see page 1060)
BMC Remedy AR System configuration files (see page 1064)
AR System server components and external utilities (see page 1127)
Defining your user base (see page 1333)
Setting user preferences (see page 1344)
Capturing server events for workflow or API calls (see page 1859)
Defining business schedules using Business Time (see page 1374)
Enabling alert notifications (see page 1410)
Assigning requests with the Assignment Engine (see page 1419)
Importing data into BMC Remedy AR System forms (see page 1969)
Enabling and disabling full text search (see page 1423)
Troubleshooting
Troubleshooting alert activity (see page 4754)
Troubleshooting full text search (see page 4689)
Database Reference Administering

Understanding the AR System database (see page 2019)
Error Messages Guide Troubleshooting

BMC Remedy AR System diagnostic messages (see page 4444)
Working with error messages (see page 4423)
Form and Application Developing an application

Objects Guide Packing lists (see page 2318)
Creating packing lists (see page 2319)
Version control in BMC Remedy AR System (see page 2324)
Using object reservation (see page 2327)
Using the object modification log (see page 2328)
Defining and managing an application (see page 2345)
Developing the application interface (see page 2373)
Securing your application (see page 2718)
Customizing applications using overlays and custom objects (see page 3031)
Defining and managing form views (see page 3114)
Customizing the home page and entry points (see page 3153)

Localizing an application to other languages (see page 3180)

Moving to production (see page 3401)
Locking objects (see page 3418)
Installation Guide Planning (see page 183)

Installing (see page 238)
Upgrading (see page 710)
Integration Guide Integrating (see page 713)
Developing an application
Making applications licensable for integration system vendors (see page 3424)
Publishing the BMC Remedy AR System functionality as a web service (see page 3430)
Introduction to Application Developing an application

Development Application development with BMC Remedy Developer Studio (see page 2244)
with BMC Remedy Understanding the AR System Navigator (see page 2265)
Developer Studio Working with perspectives (see page 2267)
Creating objects (see page 2272)
Working with existing objects (see page 2274)
Finding objects (see page 2283)
Using working lists (see page 2301)
Using the Outline tab (see page 2304)
Using the Messages tab (see page 2306)
BMC Developer Studio frequently asked questions (see page 2311)
Differences between BMC Remedy Administrator and BMC Remedy Developer Studio (see page
2312)
Development modes (see page 2337)
Optimizing and Configuring after installation

Troubleshooting Guide Performance benchmarking and tuning in BMC Remedy ITSM Deployment online
documentation.
Troubleshooting
Troubleshooting (see page 4270)
Workflow Objects Guide Developing an application

Using menu options in BMC Remedy Developer Studio (see page 2257)
Event Navigator (see page 2258)
Using buttons and menu bar items to execute active links (see page 2261)
Modifier keywords for use in workflows (see page 2264)
Defining workflow to automate processes (see page 2720)
Troubleshooting
Using Analyzer to find problems in your applications (see page 3278)
Working with the Analyzer View tab (see page 3293)
Launching the Analyzer from a command line (see page 3296)
Troubleshooting BMC Remedy Developer Studio issues (see page 4655)
BMC Remedy Approval Key concepts

Server Guide How BMC Remedy Approval Server automates approval-driven business processes (see page
68)
Installing
Starting and stopping the Approval Server (see page 602)
Approval Server post-upgrade procedures in BMC Remedy ITSM Deployment online
documentation.

Using
Opening Approval Central (see page 925)
Approving requests (see page 1017)
Configuring after installing

Configuring the BMC Remedy Approval Server (see page 595)
Administering
Setting up the approval process (see page 1623)
Adding approvals to an application (see page 3001)
Configuring BMC Remedy Approval Server logging and loopback calls (see page 4330)
Troubleshooting
BMC Remedy Approval Server logging (see page 4382)
BMC Remedy Approval Server installation and upgrade issues (see page 4273)
BMC Remedy Approval Server file locations (see page 4277)
Troubleshooting BMC Remedy Approval Server (see page 4676)
Adding approvals to an application (see page 3001)
BMC Remedy Distributed Key concepts

Server Option Guide How BMC Remedy Distributed Server Option manages distributed business requests (see page
67)

Configuring DSO for a server group (see page 351)
Configuring BMC Remedy Distributed Server Option (see page 535)
Setting up DSO to synchronize data across multiple AR System servers (see page 1796)
Troubleshooting
Configuring BMC Remedy Distributed Server Option logging (see page 4335)
BMC Remedy Distributed Server Option logging (see page 4378)
BMC Remedy Email Engine Key concepts

Guide How BMC Remedy Email Engine enables email-driven business processes (see page 64)
BMC Remedy Email Engine architecture (see page 176)
Installing
BMC Remedy Email Engine internationalization support (see page 234)
Email Engine preinstallation tasks - Windows and Email Engine preinstallation tasks - UNIX
in BMC Remedy ITSM Deployment online documentation.

Configuring the Email Engine for a server group (see page 353)
Configuring BMC Remedy Email Engine (see page 604)
Securing incoming and outgoing email (see page 684)
Configuring SSL for the email engine (see page 678)
Stopping and starting the Email Engine (see page 632)
Administering
Controlling BMC Remedy AR System through email (see page 1457)
Troubleshooting
Configuring BMC Remedy Email Engine logging (see page 4344)

BMC Remedy Email Engine logs

Debugging options for the BMC Remedy Email Engine (see page 4345)
BMC Remedy Email Engine locations (see page 4277)
Troubleshooting BMC Remedy Email Engine (see page 4661)
BMC Remedy Flashboards Key Concepts

Guide Data flow in flashboards (see page 2682)

Configuring flashboards for server groups (see page 353)
Monitoring reports by using flashboards (see page 572)
Configuring BMC Remedy Flashboards (see page 634)
Using BMC Remedy Flashboards (see page 1051)
Adding graphics to an application with flashboards (see page 2681)
BMC Remedy Flashboards overview (see page 2681)
Creating flashboards (see page 2696)
Planning a flashboard (see page 2690)
Creating flashboard variables (see page 2691)
Creating and managing flashboards (see page 2696)
Adding a flashboard to a BMC Remedy AR System form (see page 2703)
Flashboard fields (see page 3241)
Troubleshooting
Creating flashboards to collect server statistics (see page 4293)
Troubleshooting BMC Remedy Flashboards (see page 4657)
BMC Remedy Mid Tier Configuring after installing

Guide BMC Remedy Mid Tier configuration (see page 393)
Configuring reporting (see page 561)
Mid Tier cache configuration (see page 381)
Using
Using the AR System Object List (see page 901)
Running and saving searches (see page 926)
Reporting on BMC Remedy AR System data (see page 943)
Using BMC Remedy Flashboards (see page 1051)
Using customized style sheets (see page 3095)
Mid tier application development guidelines (see page 2960)
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 This document is obsolete.

Reference

BMC Remedy Encryption online documentation

BMC Remedy Encryption Security Key concepts

Guide How BMC Remedy Encryption Security enables secure communication between the
client and server (see page 66)
Planning
BMC Remedy Encryption Security options
Security policy impact on client-server communication
BMC Remedy Encryption Security compatibility
Installing
Installing BMC Remedy Encryption Security in BMC Remedy ITSM Deployment
documentation.
Upgrading
Upgrading encryption security in BMC Remedy ITSM Deployment documentation.

Configuring BMC Remedy Encryption Security (see page 689)
Troubleshooting
Troubleshooting encryption security (see page 4751)
BMC Remedy Encryption Security Release notes and notices

Release Notes BMC Remedy Encryption Security enhancement in version 9.0.00 (see page 46)

BMC Remedy Encryption Security known and corrected issues in version 9.0.00 (see
page 47)
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 (see page 64)
Installing
Installing BMC Remedy Migrator in BMC Remedy ITSM Deployment documentation.
Configuring BMC Remedy Migrator (see page 647)
Administering
Migrating applications and data between AR System servers (see page 2052)
BMC Remedy Migrator Release notes and notices

Release Notes BMC Remedy Migrator enhancements in version 9.1.00 (see page 47)

BMC Remedy Migrator known and corrected issues in version 9.0.00 (see page 47)

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.
White papers online

Performance Benchmarking Tutorial Using SilkPerformer with BMC Remedy Using SilkPerformer to measure and optimize
Mid Tier application performance (see page 3318)
KITE Scripting for BMC Remedy AR System Mid Tier Measuring mid tier performance with KITE
scripting (see page 3304)
BMC Remedy Action Request System Enterprise Quick Reference White Planning BMC Remedy AR System installation in
Paper an enterprise environment (see page 198)
Remedy Application Performance Benchmarking Best Practices Performance benchmarking and tuning in BMC
Remedy ITSM Deployment online
documentation.
BMC Remedy AR System Server 7.6 Performance Tuning for Business Performance tuning for BSM in BMC Remedy
Service Management ITSM Deployment online documentation.
BMC Remedy IT Service Management Suite Delta Data Migration Server Migrating delta data after an upgrade
Setup and Implementation
BMC Remedy Action Request System Behavioral Differences Between BMC This document is obsolete.
Remedy User and Browser Clients
BMC Remedy Action Request System Designing BMC Remedy applications Making your application accessible (Section 508
for Section 508 compliance compatibility) (see page 3228)
BMC Remedy Action Request System Web Application Security Assessment BMC Remedy security certification
and Vulnerability Mitigation Tests
BMC Remedy IT Service Management Suite Installing and Configuring Installing in BMC Remedy ITSM Deployment
Server Groups online documentation.
Integrating BMC Remedy Action Request System with Single Sign-On (SSO) Single sign-on authentication systems integration
Authentication Systems and Other Client-Side Login Intercept Technologies (see page 47)
BMC Remedy Action Request System Using the Certificate Database Tool This document is obsolete.
Using a Hardware Load Balancer with BMC Remedy Action Request System Configuring a hardware load balancer with BMC
Remedy AR System (see page 489)
Supporting Compliance Audits with BMC Remedy Approval Server Supporting compliance audits with BMC Remedy
Approval Server (see page 1891)
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 (see page 697)
Product announcements
This topic describes changes that will occur in future releases of the product. These changes can
affect the way in which you configure or run the installed version of BMC Remedy Action Request
System.
Statement of direction for Compatibility Matrix
Statement of direction for Compatibility Matrix
Note
While every effort is made to provide accurate, forward-looking guidance on product

direction to assist our customers in buying and planning decisions, we cannot guarantee
that the intentions stated here are final and binding.
Statement of direction: Compatibility matrix

May 1, 2015
This statement of direction describes changes in the BMC Remedy Action Request (AR) System
Compatibility Matrix introduced in version 9 and provides an indication of future direction.
BMC Remedy AR System supports many combinations of the most popular hardware, operating
systems, web servers, databases, and browsers on the market. This support is captured in the
published compatibility matrix. With each release, BMC evaluates support for the combinations
listed in the compatibility matrix, including additions, removals, and minimum version changes
based on customer and market feedback. All minimum versions support an "or later" policy.
Certification of newer versions by BMC typically lag behind the vendor’s release. However, as long
as the vendor respects backward compatibility, BMC does not anticipate major issues with
certification.
For any items not mentioned in this posting, the details in the compatibility matrix are not expected
to change.
Changes to database compatibility

The following list describes expected changes to the Database section of the compatibility matrix:
Remove support for the IBM DB2 database.

Remove Sybase from the compatibility matrix (removal of Sybase support has already been
announced).
Raise the minimum support for Microsoft SQL Server to 2008 SP2 from the current 2005.
Raise the minimum support for Oracle database to 11gR2 patchset 3 (11.2.0.3.0) from its
current 11gR1.
Certify the platform running on SQL Server 2014 shortly after the next release.
Certify the platform leveraging the SQL Server Always On capability in 2012 and 2014
shortly after the next release.
Changes to operating system compatibility

The following list describes expected changes to the Operating System section of the compatibility
matrix:
Add CentOS as a supported operating system (currently for BMC Remedy Mid-Tier only).
Raise the minimum support for Microsoft Windows Server to 2008 R2 x64 from its current
2003.
Drop support for Windows Server 32-bit for platform.
Note
Certification with Oracle Solaris has not been included in this release but will follow
shortly after the release.
HP-UX and AIX operating systems have not been certified for this release, and
BMC is considering dropping them from the compatibility matrix.
You can still deploy with Windows 32-bit
Changes to Web Server compatibility

The following list describes expected changes to the Web Server section of the compatibility
matrix:
Raise the minimum support for Apache Tomcat to 7.0.53 from its current 6.x.
Raise the minimum support for Microsoft IIS to 7.5 from its current 6.x.
Raise the minimum support for Oracle Weblogic to 11g from its current 10g.
Raise the minimum support for RedHat JBoss to EA 7.1 from its current 5.x.
Raise the minimum support for IBM Websphere to 8.5 from its current 7.x (due to no support
for Java 1.7).
Note

BMC Remedy Smart Reporting is currently supported using the Apache Tomcat web
server only. Future releases will expand this coverage.
Change to enabling technology compatibility

Raise the minimum support for Java to 1.7.0 Update 55 from its current 1.6 .
Change to third-party product compatibility

Raise the minimum support for Microsoft Internet Explorer to 9 from its current 8.
Intended direction for enhancements to the BMC Remedy AR System API

A common way to integrate with the BMC Remedy AR System platform is through either the C API
or the Java API. BMC has seen an increased rate of adoption around the Java API. As we develop
new features for the system, we will focus on exposing those new features through the Java API.
This focus means that some new features will not be available through the C API.
Frequently asked questions

Question Answer
What are my options if I Typically, you will need to export your data and import it to another system that is running another
am running DB2 today and database. If you need help, we recommend that you engage with BMC Professional Services or a
I want to upgrade? BMC Partner. There is currently no automated migration tool tested by BMC to move from DB2 to
another supported database.
Will not having all the Any existing implementation that leverages the C API will not be impacted. However, new system
features available to me capabilities that are introduced might not be accessible through the C API.
via the BMC Remedy AR
System C API impact my
implementation?
Will changes in the C API No, changes to the compatibility matrix are tied to a version release and do not typically impact
impact my current previous versions.
implementation?
Why did you change so As new technology becomes available, older versions might not support newer features. BMC
many minimum versions? constantly evaluates new and older versions of software and moves minimum supported
statements as we see adoption moving forward.
Why are you dropping Microsoft Internet Explorer 8 has been on a steady decline in usage (see http://www.
Microsoft IE 8? theie8countdown.com/ ) and is being phased out in many organizations. Newer approaches to user
experience typically require support for features that the vendor does not support. Resetting the
minimum to version 9 also aligns with the minimum versions published by BMC MyIT and BMC
Smart IT functionality.

Getting started
The following topics help you to get started with the BMC Atrium CMDB product documentation.
Orientation (see page 57)

Key concepts (see page 58)
User goals and features (see page 179)
If you are a system administrator and looking for information on installing or upgrading the product,
you should navigate to the BMC Remedy ITSM Deployment documentation.
About BMC Remedy AR System

BMC Remedy AR System is a professional development environment that leverages the
recommendations of the IT Infrastructure Library (ITIL) and provides a foundation for Business
Service Management (BSM) solutions. Using BMC Remedy AR System, nonprogrammers can
build powerful business workflow applications and deploy them simultaneously in web, Microsoft
Windows, UNIX, and Linux environments.
Applications built with BMC Remedy AR System can automatically track anything that is important
to the processes in your enterprise. Companies use BMC Remedy AR System applications to track
such diverse items as stock trades, benefits data, inventory assets, spare parts, and order
fulfillment. One of the most common uses of BMC Remedy AR System is to automate internal
service desks.
Orientation
Use the information in this section to understand the primary milestones for getting orientated with
the BMC Remedy AR System product documentation, the table below helps you to locate the
information to effectively work with the product.
Goal Where to go
Where do I begin? You can begin with learning the Product overview (see page 59), the key concepts (see page 58
). A Learning path is available for you to get started on the product.
What are the key The BMC Remedy AR System components (see page 97) section gives an overview of all the
components of the product? components and their value.
Where is the install and The install and upgrade information resides in the Deployment documentation area. The
upgrade information? Deployment documentation assists you with the install and upgrade tasks for all the products that
are a part of the BMC Remedy IT Service Management suite.
Below are some direct links to the Atrium CMDB specific topics from the deployment
documentation. However, it is recommended that you go through the preparing section if you are
working with install or upgrade.
Installing BMC Remedy AR System

Goal Where to go
Upgrading BMC Remedy AR System
How do I plan my system Refer to the Planning (see page 183)section to plan for your hardware and software requirement.
requirements, deployment You can also review security related information, deployment architecture and so on.
architecture and so on?
How do I configure the Refer to the configuration tasks (see page 241) section to complete the configuring tasks after the
product after installation? BMC Remedy AR System product is installed or upgraded.
How do I get started with Refer to How BMC Remedy Single Sign-On manages single sign-on (see page 72) to
single sign on understand the key concepts of the Remedy Single sign on component.
Refer to BMC Remedy Single Sign-On architecture (see page 178) to understand the technical
details of BMC Remedy Single Sign-On.
Refer to Configuring BMC Remedy Single Sign-On (see page 654) to get the configuring details
for Remedy SSO.
To manage the Administrator console, see Managing the BMC Remedy Single Sign-On
administrator console (see page 1793) topic.
How do I start using the Access the Using (see page 901)section to perform tasks related to navigating the infrastructure,
product and navigate the reporting, approving requests, and using flashboards .
User Interface?
How do I perform Refer to the Administering (see page 1059)branch to perform the following admin tasks and many
administration tasks? more :
Manage user preference

Manage security
Manage Full text search, Assignment Engine
Manage DSO settings
Manage data
How do I develop Refer to the Developing and Application (see page 2242) and Developing an API program (see
applications, and use API page 3533) sections to develop applications using the AR System platform.
programs?
Where can I find Troubleshooting section has information on resolving errors related to logs, performance, AR
troubleshooting information? System components, and so on.
Key concepts
Consult the following topics to learn about the BMC Remedy AR System :
Product overview (see page 59)

License overview (see page 85)
Access control overview (see page 88)
Application development overview (see page 97)
Architecture (see page 137)

Product overview
Use the following topics to understand how you can use BMC Remedy Action Request System
(BMC Remedy AR System) to address your business needs.
How BMC Remedy AR System enables business process automation (see page 59)
How BMC Remedy AR System products and related products enable additional value and
BSM (see page 62)
How BMC Remedy Migrator automates migration of data and objects between AR System
How BMC Remedy Email Engine enables email-driven business processes (see page 64)
How BMC Remedy Encryption Security enables secure communication between the client
and server (see page 66)
How BMC Remedy Distributed Server Option manages distributed business requests (see
page 67)
How BMC Remedy Approval Server automates approval-driven business processes (see
page 68)
How BMC Remedy AR System integrates with third-party products (see page 70)
How BMC Remedy Single Sign-On manages single sign-on (see page 72)
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 (see page 62)). You can
also create your own custom solutions.
How BMC Remedy AR System facilitates adaptability

BMC Remedy AR System is a simpler solution than hard-coded applications, which are typically
inflexible, and development toolkits, which often require extensive technical knowledge and time to
use. Instead, BMC Remedy AR System provides a platform from which even nonprogrammers can
modify ready-to-use BMC applications or create custom applications to fit their unique enterprise.
(Click the image to expand it.)

Perhaps the best way to understand the adaptability of BMC Remedy AR System is through an
example.
Example
Paul owns a small book 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
book title, number of copies, price, and customer rating. 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 books online, and to store their purchase history in a
knowledge base. He further automates the system to provide proactive book suggestions
based on the purchase history.

Using BMC Remedy AR System to implement the book store, facilitates Paul to easily
adapt and implement the changes to his business demands and expand his business.
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 (see page 140) and How BMC Remedy Distributed Server Option manages
distributed business requests (see page 67).
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 (see page 66).
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 (see
page 1442).
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 (see page
2120).

BMC Remedy Single Sign-On - The Remedy SSO is a light web application that helps in
providing single sign on and single sign off. You can deploy the Remedy SSO web
application on the same infrastructure as the AR Remedy Mid Tier. The Remedy SSO is
easier to deploy, configure, and maintain. It can be deployed in the failover cluster which
allows adding or removing the nodes easily on demand. See
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 Integrator
BMC Product Catalog
Although not based on BMC Remedy AR System, the following BMC Atrium applications provide
powerful visualization, decision support, and data discovery capabilities. They are pre-integrated
with BMC solutions for BSM and are ready to use out of the box.
BMC Analytics for BSM

BMC Dashboards for BSM
BMC Discovery Solution
BMC Remedy AR System-based solutions

The following BMC Remedy solutions for IT service and customer relationship management are
built on BMC Remedy AR System platform:
BMC Remedy IT Service Management (ITSM) Suite — Offers a complete, integrated

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

Other BMC products

Many other BMC products such as, BMC Atrium Orchestrator, BMC Service Impact Manager, and
BMC Performance Manager integrate with BMC Remedy AR System or applications based on
BMC Remedy AR System. Together, these products provide a complete solution to BSM.
For more information about these products and solutions, see the BMC Software website at
http://www.bmc.com.
How BMC Remedy Migrator automates migration of data and objects between AR
System servers
BMC Remedy Migrator can migrate BMC Remedy Action Request System (BMC Remedy AR
System) objects and data to and from the same server, from one server to another, or to many
servers. It can also migrate from a server to a file, from a file to a server, or from a file to a file, and
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.
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 emaildaemon.properties file. For more information, see Debugging options for the
BMC Remedy Email Engine (see page 4345).
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.
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 (see page 689).
BMC Remedy Encryption Performance Security (BMC Remedy Encryption
Performance)— This optional product is installed separately and it provides the following
types of encryption:
RC4 with a 128-bit key for data encryption and a 1024-bit modulus for the RSA key
exchange.

AES CBC with a 128-bit key for data encryption and a 1024-bit modulus for the RSA
key exchange. It uses SHA-1 for message authentication. This option supports the
minimum Federal Information Processing Standard (FIPS) 140-2 encryption
requirements. See FIPS encryption options in BMC Remedy ITSM Deployment
documentation.
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 in
BMC Remedy ITSM Deployment documentation.
To install BMC Remedy Encryption Premium or BMC Remedy Encryption Performance, see
Installing BMC Remedy Encryption Security in BMC Remedy ITSM Deployment online
documentation. To configure encryption, see Configuring BMC Remedy Encryption Security (see
page 689).
BMC Remedy Encryption Security includes third-party encryption software developed by the
OpenSSL Project for use in the OpenSSL toolkit (see http://www.openssl.org/ ).
How BMC Remedy Distributed Server Option manages distributed business

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

hours a day, 7 days a week

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

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

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

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

approval server then reactivates the original application and reports the result of the approval
process.
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.
Related topics
Iinformation to configure the BMC Remedy Approval Server (see page 595)
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 (see page 3533)
.
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 (see page 713)
.
How BMC Remedy Single Sign-On manages single sign-on

This section discusses the following topics:
BMC Remedy Single Sign-On Authentication (see page 74)

BMC Remedy Single Sign-On logon and logoff (see page 77)
BMC Remedy Single Sign-On HA environment (see page 78)
BMC Remedy Single Sign-On Realms (see page 79)
BMC Remedy Single Sign-On agent supporting multiple servers (see page 81)
BMC Remedy Single Sign-On Security concepts (see page 83)
BMC Remedy Single Sign-On Double Authentication concepts (see page 85)
BMC Remedy Single Sign-On is an authentication system that supports SAML V2.0 and BMC
Remedy Action Request System (BMC Remedy AR System) authentication protocols and provides
single sign-on and single sign-off for users of BMC products. BMC Remedy Single Sign-On allows
users to present credentials only once for authentication and subsequently be automatically
authenticated by every BMC product that is integrated into the system. BMC Remedy Single Sign-
On supports authentication with traditional system such as Active Directory through SAML
authentication. BMC Remedy Single Sign-On is the central integration point that performs
integration with local enterprise systems.

BMC Remedy Single Sign-On is a lightweight web application. BMC products such as BMC
Remedy IT Service Management (BMC Remedy ITSM), BMC MyIT, and BMC Analytics
applications use BMC Remedy Single Sign-On agents that redirect unauthenticated user requests
to the BMC Remedy Single Sign-On web application. BMC Remedy Single Sign-On can provide
SAML-based authentication wherein the BMC Remedy Single Sign-On web application acts as a
SAML service provider. It redirects logon requests to the SAML identity provider.
BMC Remedy Single Sign-On is easy to deploy, configure, and maintain. You can deployed it in
the failover cluster, which allows you to easily add or remove nodes on demand. BMC Remedy
Single Sign-On persists user sessions in a database instance, sharing sessions between all nodes.
BMC Remedy Single Sign-On works with Microsoft SQL and Oracle. Additionally, you can use
existing BMC Remedy AR System database infrastructure to leverage BMC product deployments
and decrease maintenance costs.
Components of BMC Remedy Single Sign-On

BMC Remedy Single Sign-On contains the following major components:
BMC Remedy Single Sign On agent — The agent filters protected resources from
unauthenticated logins. When it detects an unauthenticated request, it redirects the user to
the Remedy Single Sign On server web application. The agent defines the right domains for
the users depending on their domains. It defines the right server to communicate in a multi
server environment.
BMC Remedy Single Sign-On web application — Authenticates users and gets validation
requests from agents. If authentication succeeds, the BMC Remedy Single Sign-On web
application generates authentication tokens and stores them in its database. It now supports
SAML V2.0 and BMC Remedy AR System authentications. If SAML is selected, BMC
Remedy Single Sign-On acts like a SAML service provider and redirects authentication
requests to the SAML IDP to display the logon page with an encoded SAML authentication
request. The BMC Remedy Single Sign-On web application then processes the
authentication response by allowing or disallowing the authentication request.
BMC Mid Tier Remedy Single Sign On authenticator plugin - It validates the token from the
user request and extracts user information from the context. It then passes the information
to the BMC Remedy AR System Server through the BMC Remedy Mid Tier authentication
infrastructure. The authentication request is then processed on the BMC Remedy AR
system side by BMC Remedy Single Sign-On AREA plugin.
BMC Remedy Single Sign-On AREA plug-in — Gets user information from the BMC
Remedy Mid Tier API call as an authentication token and then makes a REST API call to
the BMC Remedy Single Sign-On web application to verify the token's validity.
Related topics

BMC Remedy Single Sign-On architecture (see page 178)

BMC Remedy Single Sign-On Authentication

Authentication settings allow BMC Remedy Single Sign-On administrators to configure BMC
Remedy Single Sign-On integration with authentication providers. BMC Remedy Single Sign-On
supports the SAML V2.0 and BMC Remedy AR System authentication processes. To configure
SAML V2.0 authentication properties, you need a Service Provider (SP) and Identity Provider
(IdP), which allow you to set connectivity between SPs and the IdP, certificates, attributes, and so
on. To configure BMC Remedy AR System authentication, you must integrate BMC Remedy
Single Sign-On by providing AR System hostname and port number. The BMC Remedy Single
Sign-On AREA plug-in then handles the authentication requests.
BMC Remedy Single Sign-On common authentication workflow (see page 74)
SAML authentication workflow (see page 75)
BMC Remedy AR System authentication workflow (see page 76)
Kerberos authentication worflow (see page 76)
Related topics (see page 77)
BMC Remedy Single Sign-On common authentication workflow

The common authentication logon workflow for BMC Remedy Single Sign-On is as follows:
1. A user tries to access a protected application by using the application-specific client (usually
from a mobile device) or a web browser.
2. The BMC Remedy Single Sign-On component (web filter or application-specific agent)
intercepts the request and, based on information about the user domain, identifies the realm
to which the user belongs.
If the configuration contains no specific domain-to-realm mappings (or mapping does not
correspond to the user domain), the default realm is used for further processing.
3. The web filter or agent forms an authentication request and sends it to the BMC Remedy
Single Sign-On server.
4. The BMC Remedy Single Sign-On server parses the request attributes and identifies the
IdP to use to authenticate the user, based on the user realm information and authentication
configuration.
Note
The authentication subprocess depends on the IdP type (SAML or BMC Remedy
AR System). The workflows for these authentication processes are described in
SAML authentication workflow (see page 75) and BMC Remedy AR System
authentication workflow (see page 76).
5.
5. After the user is successfully authenticated, a corresponding record of user sessions is

created in the underlying database.
This record includes information about user ID, the token that was issued to the user, the
session index, and the time frame for token validity.
6. The BMC Remedy Single Sign-On server redirects the request back to the web filter or
agent for further processing.
7. Based on the settings of the specific target application, the token issued for the user might
be additionally validated.
For example, the BMC Remedy Mid Tier might be integrated with the BMC Remedy Single
Sign-On Authenticator, and the AR System server might be integrated with the BMC
Remedy Single Sign-On AREA plug-in to perform this activity. During this validation, two
conditions are checked: the token is not outdated, and it is issued for the current user.
The common authentication logoff workflow for BMC Remedy Single Sign-On is as follows:
1. The user logs off from the application.

2. BMC Remedy Single Sign On removes the application agent from the agent list associated
with the user session.
3. One of the following steps occurs:
If any other application agent is associated with the user session, BMC Remedy
Single Sign-On displays a message indicating that the user is logged off from the
application.
If no other application agent is associated with the user session, BMC Remedy
Single Sign-On invalidates the user session and display a message indicating that
the user is logged off from BMC Remedy Single Sign-On. If the Final Logout URL
specific to the user’s realm is configured, the user is automatically redirected to the
specified URL.
SAML authentication workflow

Security Assertion Markup Language (SAML) is an XML-based OASIS standard for exchanging
user identity and security attribute information. SAML uses security tokens containing assertions to
pass information about a principal (usually an end user) between an IdP and a requester. SAML
V2.0 is implemented by grouping a collection of entities to form a Circle of Trust. The Circle of
Trust is composed of an SP and an IdP. The IdP authenticates users and provides the
authenticated information to the SP which hosts services that the user accesses. BMC Atrium
Single Sign-On provides support for SP-initiated single sign-on.
The SAML authentication logon workflow is as follows:
1. User accesses the protected application from a mobile device or through a web browser.
2. Web Agent redirects the user to BMC Remedy Single Sign-On console.
3. BMC Remedy Single Sign-On sends a request to IdP to authenticate user.
4. IdP presents a login form to user for authentication.
5.
5. User enters valid credentials.
Note
The IdP does authentication depending on its specific configuration - Kerberos,

RSA, LDAP or any other authentication. In case of form-based authentication, the
IdP presents a logon page to the user, and the user enters valid credentials.
6. IdP performs user authentication.

7. IdP forms authentication response and sends it back to the Remedy Single Sign On server.
8. Remedy Single Sign On server processes authentication response, validates it, and extracts
authentication token.
9. IdP then confirms user authentication.
10. BMC Remedy Single Sign-On creates a session for the user.
11. The user is allowed to access the application.
BMC Remedy AR System authentication workflow

The Action Request (AR) authentication module allows BMC Remedy Single Sign-On to use the
user accounts within a BMC Remedy AR System server for authentication. You are required to
provide only the host name and the port name to get BMC Remedy AR System authentication
running.
The BMC Remedy AR System authentication logon workflow is as follows:
1. The BMC Remedy Single Sign-On server determines that AR-based authentication should
be used.
2. The BMC Remedy Single Sign-On web application redirects the user to the BMC Remedy
Single Sign-On console logon page.
3. The user enters valid credentials.
4. BMC Remedy Single Sign-On communicates with AR System to authenticate the user
through the BMC Remedy Single Sign-On AREA plug-in.
5. AR System confirms the user authentication.
Kerberos authentication worflow

Kerberos is a network authentication protocol. It is designed to provide strong authentication for
client/server applications by using secret-key cryptography.
The Kerberos architecture is designed around messages exchanged between clients that use
kerberos services, servers that provide services, and servers that manage the Kerberos protocol
itself. The servers that manage the Keberos protocol are often called KDCs (Key Distribution
Centers), and comprise several modular services.
The Kerberos authentication logon workflow is as follows:
1.
1. User accesses the protected application from a mobile device or through a web browser.
2. Web Agent redirects the user to the BMC Atrium Single Sign-On console.
3. BMC Atrium Single Sign-On sends to web browser/mobile device a 401 un-authorized
request setting the header to “www-authenticate:Negotiate”.
4. Web browser/mobile device requests a session ticket from the Key Distribution Center
(KDC).
5. KDC provides the web browser/mobile device with the necessary Kerberos Ticket
(assuming the web browser/mobile device is authorized) wrapped in a SPNEGO (Simple
and Protected GSS API Negotiation Mechanism) Token.
6. Web browser / mobile device sends to BMC Atrium Single Sign-On the user’s access
request + the Negotiate SPNEGO Token in an Authorization: Negotiate base64(token)
header.
7. BMC Atrium Single Sign-On validates the token with KDC.
8. KDC validates the token.
9. BMC Atrium Single Sign-On creates a session for the user’s access request.
10. The user accesses the protected application.
Related topics

Configuring BMC Remedy Single Sign-On (see page 654)
BMC Remedy Single Sign-On logon and logoff

When using a single sign-on system, the normal authentication behavior is altered. The practice of
logging on when you start a product is automatically performed when the second product is
started. This change happens without any user involvement.
When you log off, you are logged off of all BMC Remedy Single Sign-On integrated products.
Logon
When a user logs on to the BMC Remedy Mid Tier, the following events are triggered:
If BMC Remedy Single Sign-On is configured for SAML authentication, the access request
is redirected by the BMC Remedy Single Sign-On web application to the external Identity
Provider (IdP); for example, the Active Directory Federation Services (ADFS) logon page.
If BMC Remedy Single Sign-On is configured for BMC Remedy Action Request System
(BMC Remedy AR System) authentication, the web application logon page is displayed to
the user.
After the user enters valid credentials, a web filter (part of the web agent) that is placed within the
web container checks to see if the request is intended for a protected page. If so, it verifies that the
user is authenticated and then displays the BMC Remedy Mid Tier UI. If authentication does not
occur, the user is redirected to the logon page.

When the user tries to access the BMC Remedy Mid Tier from another browser tab or window, the
filter checks for an existing user session, and checks to determine whether or not the user is
already logged on. If the user has already logged on, as in this case, the BMC Remedy Mid Tier UI
is displayed without the user being prompted for credentials. If the user session does not exist yet,
or the user is not already logged on, the filter does the normal token check (from a cookie) and
redirects the user to the logon page.
Logoff
When the user logs off, the BMC Remedy Mid Tier web agent sends a request to the web
application. A reference counter on the user token table in the web application increments or
decrements the application count when the user logs on or logs off an application. The reference
counter is implemented by the applications logged on to by using the BMC Remedy Single Sign-
On token.
When a user logs off an application but the application count is greater than 0, it means the user is
still logged on. The user will not be prompted for credentials when accessing applications.
If the user logs off an application and the application count is 0, it means the user is logged off from
BMC Remedy Single Sign-On. The user will be prompted for credentials when accessing
applications.
Related topic
Orientation
Troubleshooting BMC Remedy Single Sign-On log on and log off issues (see page 4761)
BMC Remedy Single Sign-On HA environment

In a High Availability (HA) environment, multiple instances of the BMC Remedy Single Sign-On
web application are deployed and form a cluster. Usually a load balancer is used as a front end to
the cluster, giving the external applications the appearance of a single server. The load balancer
distributes requests among BMC Remedy Single Sign-On nodes. However, there is no
requirement for a sticky session, because requests can be handled by any instance.
When operating as a cluster, BMC Remedy Single Sign-On functions as a single virtual server.
Therefore, certain configuration information and user sessions data are stored in the database and
shared (not replicated) between nodes. For example, when one node is configured, the other
nodes have the same information.
The following information is global to all nodes in a cluster:

Administrative accounts
Configuration of the authentication providers
Branding-related data
Issued tokens and user-session data
Role of the database

No state is stored in the BMC Remedy Single Sign-On web applications. The local (file-based)
information is almost totally absent in the BMC Remedy Single Sign-On cluster (except database
connection information - which is usually also the same). All configuration data, sessions, and user
tokens are persisted in the database and loaded from the database. To prevent the database from
becoming a single point of failure, database replication may require, but the specific settings
depend on the specific environment. Therefore, database replication is out of scope of the BMC
Remedy Single Sign-On documentation.
Related topics

Installing BMC Remedy Single Sign-On
BMC Remedy Single Sign-On Realms

Multitenancy in Remedy Single Sign On is provided through Realms. A realm is a virtual Identity
Provider (IdP) used to authenticate a domain. Each realm is mapped to a domain or list of
domains. Multitenancy is a default functionality of Remedy Single Sign On, you do not need any
specific steps to configure it, you simply need to add additional realms for different domains.
You can add multiple realms by using the Realms tab in the Administrator console. These realms
can have different authentications, for example realm 1 can have the AR System authentication
and realm 2 can have a SAML authentication. Usually a realm has one authentication provider
(SAML or AR- based) configured, except one specific case of the Bypassing SAML
Authentication. By enabling this flag you always allow the SAML authentication except when the
SAML based IDP is not available or if you are accessing the AR-based applications using the local
administrative accounts. For more information to use this type of authentication see, Enabling
bypass SAML authentication.
When multiple realms exist, the Realm tab displays a list of realm names along with domains and
realm IDs. Each realm has the same capability and helps you manage realm authentication, users,
and user groups.

Authentication process in realms

Remedy SIngle Sign On does not manage user or user groups in the application. To authenticate
BMC Remedy Mid Tier users in a realm, the BMC Remedy Single Sign-On web application
identifies and processes logon requests from various domains. The BMC Remedy Single Sign-On
web agent deployed on the protected web applications intercepts a request and, based on
configuration data stored in the database, through the necessary Remedy Single Sign On server it
redirects the user to the logon page for the realm to which the user belongs.
The web application creates a record in the session data storage and checks the Identity Provider
(IdP) configuration to define the exact IdP instance. For example, if the IdP used is an Active
Directory Federation Services (ADFS) IdP, the ADFS logon page is displayed. If you are using
BMC Remedy Single Sign-on authentication, the BMC Remedy Single Sign-On logon page is
displayed.
The web agent maps the server host name (used by the user to access a protected application) to
the full logon and logoff URLs. The logon URLs contain the information (for example, domain name
and IdP ID) required to separate different domains from one another.
BMC Remedy Single Sign-On realm architecture

Related topic
Managing realms in BMC Remedy Single Sign-On (see page 1793)
BMC Remedy Single Sign-On agent supporting multiple servers

The BMC Remedy Single Sign-On web agent is usually configured to communicate with only one
BMC Remedy Single Sign-On server. In such a configuration, the agent performs tasks such as
checking configuration, checking the Single Sign-On token, and redirecting logons and logoffs.
An advanced feature of the BMC Remedy Single Sign-On web agent supports communication with
multiple BMC Remedy Single Sign-On servers for different domains.

The mapping between a domain and a BMC Remedy Single Sign-On server ( <domain>:<url>) is
defined through the following properties in the “rsso-agent.properties” file.
sso-external-url
Agent redirects the browser (user’s request) to this url when it detects that the
request needs to be authenticated.
Agent redirects browser to this URL when it detects that the application logout is
completed (i.e. if the request refers to ‘logout-urls’).
sso-service-url
Agent uses this URL to call BMC Remedy Single Sign-On webapp APIs to:
Retrieve configuration details such as cookie name, cookie domain, and realm-
domain mappings.
Check if the token cookie from the browser (user's request) is valid and if it is
valid, retrieve BMC Remedy Single Sign-On.
Register on BMC Remedy Single Sign-On server to track other application
agents. The tracking helps the agent to know the login status of other
application agents prior to logging out.
To support multiple BMC Remedy Single Sign-On servers on an agent, set the different values of
domain to sever mapping as comma-separated strings. For example, assume that the BMC
Remedy Single Sign-On server for the domain “firstcompany” is firstcompany-rsso.bmc.com and
the BMC Remedy Single Sign-On server for the domain “secondcompany” is secondcompany-
rsso.bmc.com. Then the properties definition will be as follows:

sso-external-url=firstcompany:https://firstcompany-rsso.bmc.com:8443/rsso,
secondcompany:https://secondcompany-rsso.bmc.com:8443/rsso
sso-service-url=firstcompany:http://firstcompany-rsso.bmc.com:8080/rsso,secondcompany:
http://secondcompany-rsso.bmc.com:8080/rsso
Related topics

BMC Remedy Single Sign-On Security concepts

User credentials and authentication tokens are security sensitive data. Hence to protect such data,
HTTPS has to be configured.
Standalone
For standalone installations, HTTPS has to be configured on the Tomcat server (in the server.xml
file). After the configuration, the interactions between the user and BMC Remedy Single Sign-On
node happens through HTTPS only. But the interactions between the supported BMC application
and BMC Remedy Single Sign-On node happens through either HTTP or HTTPS, depending on
the relevant configuration.

High Availability
For High Availability installations, HTTPS has to be configured on the load balancer. After
configuration, while the interactions between the user and the load balancer happen through
HTTPS connections, the interactions between the load balancer and the BMC Remedy Single Sign-
On nodes and the supported BMC applications happens through HTTP only.

Where to go from here
Configuring BMC Remedy Single Sign-On
Related topics

BMC Remedy Single Sign-On Double Authentication concepts

Double Authentication ensures a second level authentication for the user while accessing BMC
applications. BMC Remedy Single Sign-On implements different methods of double authentication
for BMC Remedy AR System and SAML respectively.
When the authentication mechanism is BMC Remedy AR System and when a user accesses a
BMC application, the web agent redirects the user to BMC Remedy Single Sign-On. After the user
presents her/his credentials, the first level of authentication is complete. Then, BMC Remedy
Single Sign-On again prompts the user to confirm her/his password before the user gains access
to the application.
When SAML is the authentication mechanism, the IdP does both the first and second levels of
authentication. In both instances, IdP prompts the user to present the complete credentials.
License overview
AR System licensing grants the legal use of BMC Remedy AR System and is necessary for
performing unlimited operations that change the database (for example, updating requests).
Note
You do not need a license to install BMC Remedy AR System features, such as BMC
Remedy Developer Studio.
Use this section to get information about the types of licenses, license charges, and obtaining your
license key for the AR System server.

License notes (see page 87)

License types overview (see page 88)
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 (see page 243)).
To add an AR System server license, you need a license key (see Obtaining BMC Remedy license
keys in BMC Remedy ITSM Deployment documentation).
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 (see page 342).
Differences in licensing in earlier versions

This table lists the differences between licensing in BMC Remedy AR System 7.1.00 and later
releases and licensing in pre-7.1.00 releases:
Differences in licensing
Component Previous releases BMC Remedy AR System 7.1.00 and later
License keys Every license required a key. Only AR System server licenses need keys. Customers can add all
Before you could add any nonserver licenses without the need for a key.
license to an AR System
server, you had to contact
BMC to get a key.
Server groups All AR System server and user No license qualifiers are required.
floating licenses used by
server groups needed a
license qualifier.
All licenses used Each server must have its own

by a server group AR Server license and license
had to be applied key, but it shares all other
to every server in licenses with the other servers
the group. in the group.
Dedicated server Dedicated server licenses Dedicated server licenses are not used. When you upgrade to 7.1.00 or
licenses were provided for common later from a pre-7.1.00 release, dedicated server licenses are upgraded to
components such as the BMC full AR System server licenses at no cost. In addition, licenses for any
Atrium Definitive Software applications associated with the dedicated server are automatically added
Library or CMDB. to your system.

License notes
The following notes apply to BMC Remedy AR System licensing:
BMC Remedy AR System server, server option, and application licenses

Each instance of an AR System server, server add-on, and an application must be licensed.
An instance is defined as an AR System server or group of servers (that is, server group)
sharing a common database.
In addition, each AR System server must have its own AR Server license key, but the server
group feature shares all other BMC product licenses with all of the servers in the group. See
Licensing for server groups (see page 254) 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 (see page 243)). 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.
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 (see page
1333).
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 (see page 3424).
Access control overview

This section describes user and group access, role-based access, multitiered access, and how
licensing affects access control.

User and group access overview (see page 90)

Role-based access overview (see page 93)
Multitiered access control model (see page 94)
How licensing affects access control (see page 96)
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.
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 (see page 91)). 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.
Administrator Regular groups are groups to which you assign a
Sub specific list of users. Computed groups are groups
Administrator to which users are assigned based on their
Customize memberships in groups included in an expression.
For example, you can create a computed group
definition such as (A AND B) OR C AND NOT D.
This computed group includes users who are
members of both groups A and B, or members of
group C, but not members of group D.
Implicit A group to which a user automatically (or Any dynamic groups that you create.Dynamic
implicitly) belongs by virtue of the Public groups use the contents of special fields to
contents of certain fields in a request. Submitter determine group membership.
You cannot assign users to implicit Assignee
groups. All users are members of Public. Assignee
You use the other types of implicit groups Group
to control access to requests (row-level
database access).
For more information, see Licensing BMC Remedy AR System (see page ).
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" (see
page 92), 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 (see page ).
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
Role-based access overview

The system forms are added to a single deployable application. In deployable applications, access
permissions are based on roles. Like groups, roles have permissions to access forms, fields, active
links, and so on. Unlike groups, however, roles are defined for an application and are then
associated with groups on the server where the application is deployed.

Roles make deployable applications easy to install on multiple servers. You can assign users to
groups, then associate the groups with roles. This enables you to install an application on servers
that have different groups without redefining the application's object permissions for each server.
The following table lists the roles used to access the deployable applications:
Type of roles Description
Alert Manages alerts in the user alerts list.

Administrator
AR Definition Allows read access to the AR System metadata forms. The AR Definition Administrator also has the ability
Administrator to modify definitions through configurations.
Archive Configures and manages the archive policies. The Archive Administrator performs the following tasks:
Administrator
Accesses the AR System Archive Manager console
Enables and disables system-wide archiving
Enables and disables individual archive policies
Runs an on-demand archive process
Exports and deletes archive data
Email Engine Configures the Incoming and Outgoing mailboxes to work with the mail server and manages email
Administrator templates.
Home Page Specifies the default home page for a server and configures the AR System Customizable Home Page.
Administrator
Licensing Configures and manages system, user and application licenses.

Administrator
Logging Configures and manages the system logs.

Administrator
Reporting Defines who has access to view a report. Views and manages the reports shared by all users.
Administrator
User Adds and deletes users in the AR System server, manages user permissions and user preferences.
Administrator
Notes
The AR System Administrator has all the rights defined for the above roles.
To simplify, user access is usually described in terms of group permissions. For
the deployable applications that use role permissions, the user access is ultimately
determined by the groups that are mapped to the roles.
For more information, see Creating and mapping roles (see page 1266).
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
Remedy point, users must enter a valid user name, a password, and, as an option, an authentication string. BMC Remedy AR
AR System servers check the user name, password, and authentication string each time a client requests a transaction,
System such as when opening a form or changing a field. If your BMC Remedy AR System server is configured to allow guest
server users, such users can log in to the server without a valid user name or password. See User form access (see page
1338).
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
link workflow actions. For example, you might allow support staff to trigger several active links appropriate to their work but
not allow other users to trigger those active links. Groups do not automatically have access to the field associated with
an active link. You must grant them access to the active link and to the field. For active links that fire when users click
a button or choose a menu item, the users must have access to both the button or menu item and the active link to
trigger the active link.
Active When you create an active link guide, you specify the groups that have access to it. To access an active link guide, a
link user must have permission to each active link in the guide and to the guide itself. If a user has access to all active
guide links in a guide but not to the guide, the 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.
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 (see page 90)
.

Although licensing is not a component of access control, licensing can affect a user's ability to
perform an operation that you grant the user permission to perform. For example, if a user is a
member of a group that has Change permission to a field but you did not give appropriate write
license, the user cannot change the field.
Application development overview

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

BMC Remedy AR System application components (see page 97)
Application localization (see page 123)
An example BMC Remedy AR System application (see page 124)
Archiving overview (see page 134)
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.
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 (see page ).
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 (see page 103).
Association — If you want to create a relationship between two different forms in BMC
Remedy AR System, you can create an association. Association is a new object added in
BMC Remedy Developer Studio which is used for creating relationships. These
relationships are used in various BMC applications.
BMC Remedy AR System forms overview
Forms are the foundation of BMC Remedy AR System. A form captures and displays information
and a set of forms can be grouped into an applications. An AR System application is a server
object that contains references to one or more forms. When an application references a form, BMC
Remedy AR System automatically includes all the workflow and other components (such as
menus) associated with the form in the application.
Sometimes a single form can contain all of an application's functionality. For example, a small
application that tracks product defects can use a single defect-tracking form to capture and display
all required information.
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 (see page 115)). Some fields can have attached menus
that help users fill in the form (see Field menus (see page )).

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 Description
type
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- These forms contain display-only fields that enable users to accomplish specific tasks. These forms are typically used
only 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 (see page 104)

Workflow actions and execution options (see page 107)
Workflow qualifications (see page 113)
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 Where action is

by 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 (see page 108)

Workflow execution options (see page 110)
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 (see page 2818) topic.

Workflow actions
Action Description Active Filter Escalation

link
Change Changes the appearance of fields. For example, a Change Field action can perform +
Field one or more of these actions:
Moves the cursor or keyboard focus to a field.

Hides or displays a field. For example, an active link might hide all fields
related to telephone problems when users report network problems.
Changes a field's accessibility to read-only, read/write, or disabled.
Changes the color of a field label or trim text.
Changes the menu attached to a character field. For example, if a form for
scheduling a meeting has a field for the building, the menu of meeting rooms
attached to the meeting room field might change to match the specified
building.
Refreshes the data in a table field.
Changes the label of a field.
Expands or collapses a collapsible panel field.
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 +
Window load some default data. Or it can open a Modify window with requests matching a
specified qualification. This action can also open a dialog box. Data can be passed
between the dialog box and the window that calls it. Processing of active links from
the calling window is suspended until the dialog box interaction is completed.
Push Changes the values of fields in another request to the values in the current request + + +
Fields (that is, it "pushes" the values from the current request to another request). This
action can also change the value to a keyword or a function. You can use Push
Fields to set values in related requests or to create requests that are associated with
the current one. For example, you can use this action to create multiple work orders
for a telephone connection, a network address, and new furniture when an employee
is hired.
Run Runs a separate process (program) on the server for filters and escalations or on the + + +
Process Windows client or server for active links. For example, a filter can send a page, or an
active link can launch a browser on a user's desktop.
Service Works with an AR System web service to obtain external services or with a Set + + +
Fields filter action to consume an internal AR System service.

Action Description Active Filter Escalation

link
Set Sets fields on a form to specified values. For example, a filter can automatically set + + +
Fields the Status field to Assigned every time a name is entered into the Assigned To field.
The value set in a field can be static (always the same), a keyword value, or a value
retrieved from another data source.
Workflow execution options
Execution options determine when workflow runs. For active links and filters, you specify what
event triggers the workflow; for escalations, you specify the execution schedule for the workflow.
For all workflow components, you can refine the execution option by adding a qualifying statement
that tells the system which set of actions to run if the additional criteria are met and which set to
run if the criteria are not met.
Active link and filter execution options
The following table lists examples of execution options for active links and filters. For a complete
list, see Defining workflow execution options (see page 2736).
Execution options for active links and filters
Execution Description Active Filter

option link
Button/Menu Executes when a user selects the button or menu item associated with the active link. +
Field
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 +
Hover on Data display tooltips, use 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 +

Execution Description Active Filter

option link
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 (see page 112).
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 (see page 2788).
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:
Core fields in a regular form (see page 114)

Field types (see page 115)
Field characteristics (see page 116)
Fields have properties that determine their structure within BMC Remedy AR System. For an
alphabetical list of field properties, see Field properties (see page 2646).
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 (see page 2566).

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 (see page 2565).
Field type Description
Data Contains data values stored in database tables. You can set these characteristics of data fields:
Whether users can access the field and, if so, whether they can only view the field or also change its
contents
The type of data that the field can contain (such as characters, integers, dates, or times)
The amount of information that the field can contain (field length)
Whether the field is visible or hidden
Whether the field is enabled or disabled
Whether the field is required, optional, or display-only (A display-only field is a temporary field for which no
space is allocated in the database.)
Where the field appears on the form
How the field is displayed (for example, its label and physical appearance)
How information is entered into the field (for example, by typing or by selecting items from a list or a menu)
The field's default value
Whether fields are indexed for faster searches
Table Displays data from other requests in the context of the current request. Table field styles are list view, tree view,
cell-based, results list, and alert list.
Attachment Attaches files to requests
View Provides a browser window in a form. The browser can display any URL, HTML content, or file format (including
contents of attachments) that is compatible with a browser.
Data Augments BMC Remedy AR System with HTML-based content such as web pages, flashboards, and other
visualization graphics that can interact 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
list required mode (New or Search). BMC Remedy AR System automatically generates the contents of the application
list. The entry points that a user sees in the list are only those to which the user has access. Any form that
contains an application list field can be used as a home page . A home page is a single point of access into BMC
Remedy AR System.

Field type Description
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

Menu Description
type
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
dictionary configuration interfaces. They are generally not used to help users perform their work.
Associations overview
An association is a BMC Action Request (AR) System server object that describes relationships
between entries in BMC Remedy AR System forms. The association enables you to manage
relationships between entries in two forms to support referential integrity, cascade deletes, and
archiving related entries.
An association defines a relationship between entries in two forms. The relationship can have three
cardinality options: One to One, One to Many, and Many to Many. For one-to-one and one-to-many
relationships, an association between two forms is defined by specifying one form as primary and
another form as secondary. For these relationships, the primary form can have only one entry in
the relationship. For many-to-many relationships, there are no primary and secondary forms.
Note
BMC Remedy AR System associations are used in BMC Remedy ITSM application
primarily for archiving. You can also use these associations with RESTful APIs to get
related entries. For more information, see Operations on entry objects (see page 3543).
The following sections are provided:
Understanding the value of associations (see page 118)

Cardinality (see page 118)
Relationships (see page 119)
Type of associations (see page 121)
Qualifications (see page 122)
Permissions (see page 122)
Introduction to the Association Server Object (see page 123)
Related topic (see page 123)

Understanding the value of associations

Associations can be used to describe the data model for an application. You can understand an
application easier with associations. Enforced associations can eliminate the need to create
workflow to restrict operations or to remove related data when an entry is deleted. Reducing the
amount of workflow needed for an application again makes it easier to understand your
applications.
Associations can also be used to govern the behavior of archive definitions. For more information,
see Defining associations to follow (see page 1900).
Cardinality
Each association has cardinality, which dictates how the entries in the two forms are related. The
options are:
One to One — This cardinality describes a relationship in which an entry from the primary
form can be related to exactly zero or one entry in the secondary form.
One to Many — This cardinality describes a relationship in which an entry from the primary
form can be related to zero or more entries in the secondary form.
Many to Many — This cardinality describes a relationship in which an entry from the primary
form can be related to zero or more entries on the secondary form and an entry from the
secondary form can be related to zero or more entries on the primary form.
Note
All cardinality options may have an entry that is related to no other entries. For example,
a one-to-one relationship between an employee and email address includes the
possibility that an employee might not have any email addresses.

Relationships
Data relationships defined by associations may be enforced (strong) or not enforced (weak).
Enforced associations
If an association is defined as enforced, the BMC Remedy AR System server ensures data
integrity is maintained. Data integrity means that the server will enforce the cardinality of the
association and will ensure referential integrity. Thus, an entry will not be able to refer to another
entry that does not exist.

Note
Associations enforced on forms are also enforced on the archives of those forms.
Only one-to-one and one-to-many cardinality can be enforced. You cannot create an enforced
many-to-many relationship in BMC Remedy AR System. The server performs the following
functions for the enforced association:
If an entry is deleted from the primary form, the server deletes all related entries from the
secondary form (cascade delete).
Server does not allow duplicate primary key values in the primary form. For example, each
employee must have unique ID.
Server does not allow entries in the secondary form with invalid foreign key values. For
example, an entry in the contact form must reference a valid employee.
Server does not allow changing primary key values in the primary form if they are
referenced in a secondary form. For example, you cannot change an employee ID if that
employee is referenced in a birth information form.
For one to one associations, the server does not allow creation of entries in the secondary
form if that breaks the cardinality defined by associations. For example, it will not allow
creation of a second birthday entry for the same employee.
Note
If an enforced association is created between forms that already contain data, it is not
necessary that the existing data should have referential integrity. However, any changes
to the data after the association is created will follow enforcement and should have
referential integrity.
Unenforced associations
If an association is not enforced, the BMC Remedy AR System server allows creation of records
even if the creation breaks the cardinality defined by the association or the referential integrity. If
an association is not enforced, the server does not perform the actions listed above for enforced
associations.
Unenforced associations provide a way to describe data relationships that are not directly enforced
by the server. These associations may be otherwise enforced, by defining workflows in BMC
Note

BMC Remedy Data import tool has an option to disable association enforcement while
importing data. For more information, see Form mapping data options (see page 2167).
ARMergeEntry api provides an option to disable association enforcement as well. For
more information, see ARMergeEntry (see page 3981).
Type of associations
Entries in forms may contain direct references to each other, or may be related through a third form
that contains references to each of the related entries. The association type describes which of
these approaches is used.
Association Cardinality Can be Description

type Enforced?
Direct One to Yes Direct associations are primary key and foreign key associations between two forms.
One
Multiple fields from main form can be used as a primary key and similarly multiple
One to fields from the secondary form can be used as a foreign key. In other words, each
Many field of the primary key maps to a field in the foreign key and is called direct
association.
Indirect One to Yes These types of associations are called external associations where the associations
One are created by using a third form. This third form, called an association form, stores
the foreign key for both the primary and secondary forms. Multiple fields from the
One to primary form can be mapped to the same number of fields on the association form
Many
and similarly multiple fields from the secondary form can be mapped to the same
number of fields on association form.
Many to No
Many
Direct associations
Direct associations involve only two forms, and require that references from one form to the other
use only data that is present on the forms. Direct associations can be used for one-to-one and one-
to-many relationships. They cannot be used for many-to-many relationships. In the following
example, the Employee Phone form directly holds reference to Emp ID of the Employee form.
Employee Employee Phone
Emp details Emp ID Emp ID Phone details
Indirect associations

Indirect associations include a third form that contains references to each of the related
forms. Entries in the two related forms in an indirect association do not have references to each
other. Indirect associations can be used for any kind of relationship, and only an indirect
association can be used for a many-to-many relationship. In the following example, the Employee-
Department form (third form) contains references to the two related forms: Employee and
Department.
Note
Whether the association is enforced or not, for an indirect association, the server will
always delete related entries from association form if an entry is deleted either from
primary or secondary form.
Employee Employee-
Department
Emp Emp Emp Dept

details ID ID ID
Qualifications
When defining an association, you have the option of specifying a qualification for each of the
forms involved. Qualifications allow different relationships between entries in the same two forms
or the storage of multiple relationships in a single indirect association form.
When you specify qualifications, only entries matching the qualification are related to the
association. For example, you might have a Phone details form that includes a Phone Type field
indicating that an entry is an office phone number or another type of phone number. You could
then create different associations between an employee form and the phone details form:
one-to-one association between an employee and an office phone

one-to-many association between an employee and all other phones
You would add a qualification in the first association requiring that the field on the telephone
number form be office phone option.
Permissions
An Association object does not have any permissions. Only administrators are allowed to create,
modify and delete associations. All other users can view an association, if they have access for
viewing the all the fields and forms used in that association.

Introduction to the Association Server Object

The following video (6:25 minutes) explains how the Association Object can be used to establish
relationships between entries in two BMC Remedy AR System forms to support referential
integrity, cascade deletes, and archiving related entries.
Related topic
Using associations (see page 2294)
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 (see page 3180).

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 (see page 124)

Goals of the animal tracking application (see page 127)
About the wild animal park (see page 128)
Putting the example application to work (see page 129)
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 (see page 124)

Analyzing workflow (see page 125)
Defining business rules (see page 126)
Mapping business rules to workflow components (see page 126)
Considering integrations (see page 127)
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 (see page 129)

Example application - The tiger is injured (see page 130)
Example application - The tiger is traded to another zoo (see page 131)
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.

Archiving overview
The archive feature of BMC Remedy AR System provides a convenient way to periodically store
data (not definitions) from a form to an archive form; this reduces the amount of data accessed
during searches on the main form, thus improving system performance. Archiving applies to all
types of forms, except display-only forms, vendor forms, and join forms. You can manage the
production system efficiently and utilize the available infrastructure and resources optimally. When
you archive your data, you can improve system performance and enable data retention.
By archiving, the main application has fewer records which results in quicker searches and better
performance, while the records are still archived. You can also reduce the database size by
periodically extracting archived data.
The main form is the form on which archive is set (data is read from this form), and the archive
form is the form to which data is copied. It is important that when you archive the main form, the
related forms are also archived. For providing ability to archive related data, you can explicitly
create associations between forms in the Developer Studio. For more information, see Defining
associations to follow (see page 1900).
The following image displays the concept of archiving in BMC Remedy AR System.

Related topics
To know more about these concepts, see BMC Remedy archiving concepts (see page 136)
.
To know more about properties for form level changes, see Configuring data archiving for a
form (see page 1896).

Archiving concepts
This topic provide information about the archiving concepts introduced in BMC Remedy AR
System 9.0.
AR System Archive Manager console

Starting 9.0 release, you can manage archive definitions through forms. A new AR
System Archive Manager console uses the AR System Archive Policy form to allow authorized
users to enable, disable, describe, and control the age of archived records. It also allows the user
to perform an archive on demand, even if the console has disabled the archive.
The Archive Manager console displays the values from the archive definition, and allows the user
to override or accept those values. The archive definition controls the appearance of an archive in
the console, which is an element of the form definition that can be accessed using BMC Remedy
Developer Studio.
You can also export and delete your archived data directly from your application using the AR
System Archive Manager console now. For more information, see Managing the archiving process
(see page 1911).
Age qualification
This is a new parameter added in the archive definition, which specifies that the records should be
archived when they have reached a specific age. The definition includes the field on the form that
is used to determine the record’s age, and the age in number of days after which records should
be archived. You can set this definition on the archive panel for each form. For more information,
see Configuring data archiving for a form (see page 1896).
The age specified in the definition appears in the Archive Manager console as well. You can
choose to override the value from the console.
Note
Before 9.0 release, the archive qualifications included specification of the age at which
entries were archived, along with other information that indicated which records should be
archived.
After upgrading to 9.0 release, the existing archive definitions will be updated so that they
appear in the Archive Manager console with an age specified as zero. Because the
qualification still includes an age component, the records are archived at the greater age
in the qualification and at the age specified in the console. By default, the archiving
happens as before, but the age of the archived records will not be entirely controlled from
the console. To resolve this issue, you can adjust the definitions so that the age of
records is not added in the qualifier.

Associations to follow
The form definition includes a list of associations that is followed when an entry on the form is
archived. The associated records in other forms are archived with the original entry in a single
transaction so that a parent and all of its related child records can be archived together. For more
information about understanding associations, see Associations overview (see page 117).
For more information, see Archiving overview (see page 134).
Note
Indirect associations having Many to Many cardinality cannot be followed for archiving.
Even if you select those associations, they will be ignored during the archiving process.
Include in archive policy

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

BMC Remedy AR System architecture (see page 138)

AR System server architecture and scalability (see page 147)
AR System database server (see page 159)
BMC Remedy Mid Tier architecture (see page 160)
BMC Remedy Migrator architecture (see page 165)
BMC Remedy AR System web services architecture (see page 166)
BMC Remedy AR System API architecture (see page 168)
BMC Remedy Single Sign-On architecture (see page 178)
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 (see page 138)

BMC Remedy AR System client server architecture (see page 141)
BMC Remedy AR System client server communication (see page 143)
BMC Remedy AR System clients (see page 145)
BMC Remedy AR System functional components

BMC Remedy AR System is based on a client/server architecture and includes the following
functional environments:
Presentation— The presentation piece of BMC Remedy AR System is responsible for

presenting services and displaying data to clients through various interfaces. These
interfaces include:
browsers
cell phones
PCs
Personal Data Assistants (PDAs)
BMC Remedy Developer Studio
API programs
All these interfaces enable you to access BMC Remedy AR System. Clients can be
thought of as consumers of services that the AR System server provides.
Business processing— This portion of the architecture includes:
BMC Remedy Mid Tier
AR System server
Server functions such as the Distributed Server Option (DSO), and BMC Remedy
Approval Server
The BMC Atrium Integration Engine (AIE) or Atrium Integrator (AI)

Web services
The business processing piece of BMC Remedy AR System is responsible for
providing services to clients and processing the data entered through clients.
Applications that reside within the business processing environment act as liaisons
for the clients and the database, enforcing the rules of your business processes.
Data storage — The data storage element contains the actual data for the system. BMC
Remedy AR System supports Oracle 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 Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation.)
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 (see page 144)
Communications between AR System servers and database servers (see page 144)
Many-to-many connections (see page 144)
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 (see page
141). 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 Administrator tasks:
browser
Create groups and roles.
Create users and assign licenses.
Manage AR System server settings and licenses.
User tasks:
Access BMC Remedy AR System forms and applications to create, submit, search and modify requests.
Receive and respond to AR System notifications
Chart data
Generate reports
Display alerts in the Alert List form, which can be refreshed automatically at specified intervals or manually at
any time.
Search records, run or generate reports, view flashboards
Developer clients
The developer clients are used to create, modify, and extend BMC Remedy AR System
applications.
Client Tasks
BMC Remedy Developer Developer tasks:

Studio
Create and update application, forms, and workflow.
BMC Remedy Mid Tier Administrator tasks:

Configuration Tool
Modify mid tier settings for AR System servers, passwords, logging, caching, and
authenticating web services.
Specify home page and preference and catalog servers.
BMC Remedy Data Import 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 Administrator tasks:

interface (CLI)
Connect to the AR System server to import and export object definitions without the
graphical user interface of BMC Remedy Developer Studio.
Automate tasks.
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.

Client 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 (see page 145).
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 (see page 3431).
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 Processes data it receives from AR System clients, and passes the data to the database server to be
server 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 (see page 148)

AR System server multithread architecture (see page 151)
AR System server queues (see page 153)
AR System server threads (see page 156)
AR System server processes (see page 158)
For more information about configuring AR System servers, see:
Configuring AR System servers (see page 255)

Configuring server groups (see page 342)

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 (see page 3533) 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 (see page 1410).
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 (see page 722).
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 (see page 828).
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 (see page 840).

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 (see page 838).
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 (see page ).
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 390602

Indexing
Escalation 390603
Fast 390620
List 390635

Queue type RPC program number
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 (see page 154)

Alert queue (see page 154)
Escalation queue (see page 155)
Fast queue (see page 155)
List queue (see page 155)
Private queues (see page 155)
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 (see page 298).
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 (see page 3533).
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 (see page 298).
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 (see page 298).
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 (see page )). To

configure a private queue, see Defining queues and configuring threads (see page 298).
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 (see page 257).
For more information on Private Queues, see the blog Utilizing Private Queues shared on BMC
Communities.
AR System server threads

The term thread is short for thread of execution. Threads enable the server to process concurrent
client requests. Each thread within the multithreaded server can carry out a client request before
returning to the queue to process the next one. Start only as many threads as your database and
system resources can reasonably support. The total number of threads cannot exceed the number
of database connections available to the AR System server.
All threads within a process share network and system resources; therefore, consider carefully the
available resources of your system and network when establishing the minimum and maximum
thread settings for your server queues.
BMC Remedy AR System uses the following types of threads:
Dispatcher thread (see page 156)

Worker threads (see page 157)
Thread manager (see page 157)
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 (see page 274).
Related Topic
Defining queues and configuring threads (see page 298)
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
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation.
The server is implemented as several service processes that are normally started automatically
when the server host is powered up.
The AR System server has no direct user interface. Clients, such as the mid tier and other
applications, communicate with BMC Remedy AR System by means of a well-defined application
programming interface (API). An API is one possible way to integrate with BMC Remedy AR
System. The APIs use remote procedure calls (RPCs) to communicate with the server. Both a C
interface and a Java interface are available.
The AR System server processes all data entered through a client. As the workflow engine
between client and database, the server writes data to the database when a request is created and
retrieves data from the database when a client requests it. The server verifies that a user has
permission to perform each transaction, thereby enforcing any access control defined in an

application. The server also continuously evaluates the data in the database and each transaction
to determine whether the server should perform workflow. The server might also perform workflow
on a timed basis.
When a client submits a request to the server, the request enters through the API, goes through
access control and data validation, filter processing, and then transactions are committed to the
data repository as appropriate.
Following are the key processes in the AR System server:
arserver process — arserverd is for UNIX or arserver.exe on Windows; the primary AR

System server process. It handles requests from the clients and interacts with the database.
Plug-in server process— A companion process to the AR System server. It loads
configured plug-in modules to interface with external data while processing vendor forms,
validates users with external authentication sources, and extends filter workflow. When the
AR System server needs to access a plug-in, it interfaces with the plug-in server to perform
the operation.
Email engine process — Java on UNIX or aremaild on Windows; the process that links
arserver process with email systems. For example, users can submit service requests to
an AR System server by sending an email message to an email account. In addition,
workflow can cause email messages to be sent to particular email addresses as a
notification option.
AR System database server

BMC Remedy AR System uses standard relational database engines for the actual storage and
retrieval of data. Architecturally, the database server is an independent set of processes that are
completely separate from the AR System server processes. Physically, the database server
processes can be running on the same server host as the AR System server or on a different host.
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 was locally owned.
Because the AR System server manages all workflow, applications are independent of the
database. Therefore, applications created on an AR System server running one type of database
can easily be moved to a server running a different type of database. BMC provides a simple export
/import utility for this purpose.
BMC Remedy AR System is not a database application in the typical sense. All of the workflow is
managed by the AR System server, so proprietary database features such as triggers and stored
procedures are not used. An application created on an AR System server running one type of

database engine can easily be moved to a server running a different database engine through a
simple export/import process.
The user or administrator of AR System clients does not need to know anything about SQL or the
underlying database.
BMC Remedy AR System workflow components can search for records (requests) in the AR
System database and act on the results of the search. Clients can use the following types of
searches:
Query-by-example (QBE)
Advanced search
Predefined
Recent
An administrator can create and store searches that are commonly performed by users. A user can
define personal searches for forms to which the user has access.
BMC Remedy Mid Tier architecture

Use this section to understand the BMC Remedy Mid Tier architecture and its components.
BMC Remedy Mid Tier functional components (see page 160)

BMC Remedy Mid Tier scalability (see page 163)
Multiple browser sessions in a distributed mid tier environment (see page 163)
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 (see page ).
BMC Remedy Mid Tier serves as a client of the AR System server and as a server to the browser.
The mid tier enables you to view BMC Remedy AR System applications on the web and access
the AR System server from a web server. It also provides instructions to the browser in the form of
document markup and downloadable scripts. These instructions describe how to present
application data and how to interact with the user.
BMC Remedy Mid Tier translates client requests, interprets responses from the server, handles
web service requests, and runs server-side processes that bring BMC Remedy AR System
functionality to web and wireless clients. A browser is a generic client that has no inherent
knowledge of any application that might run within it. By acting as an interpreter, the mid tier allows
a browser to become a fully functional BMC Remedy AR System client.
Note

While accessing the applications using BMC Remedy Mid Tier, you can open multiple
browser windows using workflows. All the forms opened using the workflows are closed
after you log out. But if you make any changes to open the forms (for example, change
the URL in web address bar or refresh the page or access any other forms by typing form
name) or if a new browser window or tab is opened and other forms are accessed. Such
windows are not closed by the mid tier after you log out, but a session timeout error is
displayed if you perform any operations on them.
The BMC Remedy Mid Tier requires a Oracle Java Server Pages (JSP) engine, that is supported
by AR System. For a list of supported engines, see Compatibility matrix in the BMC Remedy ITSM
Deployment online documentation. Apache Tomcat is bundled with the mid tier and is installed with
the mid tier by default.
The mid tier leverages a Java servlet engine and includes a collection of servlets plugged in to the
web server to serve forms, images, and other resources. The servlet engine facilitates
communication between the browser and the web server. It provides components and add-in
services that run on the web server.
The web server manages the transfer of all HTML content to the browser. Infrastructure
components, such as servlets and other services (special Java classes), translate client requests
and interpret responses from the AR System server.
The main components of the mid tier infrastructure are:
Web server (see page 161)

Oracle JSP engine (see page 161)
Oracle JSP servlets (see page 161)
JAVA API (see page 162)
BMC Remedy Mid Tier Configuration Tool (see page 162)
Report Console overview (see page 162)
Crystal reports and mid tier architecture (see page 162)
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 Compatibility
matrix in the BMC Remedy ITSM Deployment online documentation.
Crystal reports and mid tier architecture

To make Crystal reports available to BMC Remedy AR System Web users, the mid tier uses the
AR Web ReportViewer to communicate with the Central Management Server (CMS). The AR Web
ReportViewer passes the report query, user credentials, and other report information to the CMS
for processing.
The CMS is the server component of BusinessObjects Enterprise and Crystal Reports Server. It
listens for and executes report requests, using the BMC Remedy AR System ODBC driver to
retrieve the BMC Remedy AR System data, publishes the report in the Crystal environment and
renders it for display in the browser.
The AR Web ReportViewer is a component of the mid tier. It can be installed together with the mid
tier or as a separate component, but it must reside on the same computer as the CMS.
Once the necessary components have been installed together and configured, any authorized
BMC Remedy Mid Tier can direct requests for Crystal reports to the mid tier or AR Web
ReportViewer on the Crystal reports server.

You must use one of the following configurations:
Install BMC Remedy Mid Tier on the same Windows computer as the CMS. In this case the
AR Web ReportViewer is installed as part of the mid tier.
Install the mid tier on a separate computer (any supported platform), and install only the AR
Web ReportViewer on the same Windows computer as the CMS.
BusinessObjects Enterprise or Crystal Reports Server and the AR Web ReportViewer must be
installed on a Windows computer because the CMS uses the AR System BMC Remedy ODBC
Driver to contact the AR System server when retrieving report data.
BMC Remedy Mid Tier scalability

The strategy for processing and serving browser-client requests is based on several components.
These components work together to take input from the client and compute a response that the
user sees in the browser as Dynamic HTML (DHTML). These BMC Remedy Mid Tier components
do not run in a separate proprietary process, but in the JSP engine using standard web protocols.
The use of JSP servlets makes the mid tier scalable in the following ways:
Multiple threads connecting to a servlet can handle many concurrent users.

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 (see page 463).
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
(see page 381).
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 (see page 465).
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 (see page 465).
For information about configuring this feature within a BMC Remedy IT Service Management Suite
hub and spoke system, see Registering hub and spoke servers.
BMC Remedy Migrator architecture

BMC Remedy Migrator integrates with BMC Remedy AR System through existing application
programming interfaces (APIs) and requires no additional integration work. You can install BMC
Remedy Migrator on a client workstation and run it independently of BMC Remedy AR System.
The APIs handle all communication between BMC Remedy Migrator and AR System servers.
BMC Remedy Migrator and AR System server integration


In addition to server objects, BMC Remedy Migrator can transfer data entries from one or more
BMC Remedy AR System forms. You can select single, multiple, or searched sets of data. You can
migrate data immediately or save your migration in a script to be run later.
Related topics
How BMC Remedy Migrator automates migration of data and objects between AR System servers
(see page 64)
Installing BMC Remedy Migrator in BMC Remedy ITSM Deployment documentation.
Configuring BMC Remedy Migrator (see page 647)
Migrating applications and data between AR System servers (see page 2052)
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 (see page 166)
Information flow for consuming a web service in AR System server (see page 168)
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. 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. The Set Fields filter action is finished.
Consuming an external web service with BMC Remedy AR System
BMC Remedy AR System API architecture

Use this section to learn about the BMC Remedy AR System API architecture.
BMC Remedy AR System plug-in API architecture (see page 168)

BMC Remedy AR System C and Java API architecture (see page 171)
BMC Remedy AR System REST API architecture (see page 175)
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 (see
page ). 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 (see
page 719).
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 (see page ) describes the purpose and use of each
BMC Remedy AR System C API function. BMC Remedy AR System plug-in API functions (see
page ) 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 (see page ) 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 (see page ) 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 (see
page 4253) and the Java API documentation HTML files in the ardocVerNum.jar file in the
\Arserver\Api\doc folder (Windows) or the /ARServer/api/doc folder (UNIX). To access the Java
API documentation, unzip the ardocVerNum.jar file to create a tree of directories, then open the
index.html file.
Choosing to use the Java API
Use the BMC Remedy AR System Java API to perform the following tasks:
Write server-side web applications that you access through the Java server page (JSP) or
Java servlets web tier layer.
Implement BMC Remedy AR System clients in Java.
Comparison of the Java and C APIs
The BMC Remedy AR System Java and C APIs have a number of differences, for example:
The Java Virtual Machine (JVM) uses garbage collecting functions to automatically
deallocate objects that are created with the Java API. The C API includes a set of memory
deallocating functions that you can use to deallocate memory.
In the C API, the control parameter provides server access information with every call. In the
Java API, the ARServerUser object encapsulates this information
The C API and Java API have different naming conventions.
BMC Remedy AR System REST API architecture

The API is a web service that conforms to the architectural principles of Representational State
Transfer (REST). Each API is called by issuing a standard HTTP request method: POST, GET,
PUT, or DELETE (more commonly known as the CRUD operations: Create, Read, Update, and
Delete). The REST API is a simple stateless architecture that runs over the HTTP. The advantage
of REST is having a limited number of operations for the interactions between clients and services.

The REST API uses the base URI for the web service, such as https://<localhost>:<port>
/api/{namespace}/{version}
api - is the default prefix.
namespace - is used to help separate the different APIs.
version - is the version used for particular REST API.
For more information about the REST API, see BMC Remedy AR System REST API overview (see
page 3535).
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.
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 (see page 4345) and EmailDaemon.
properties file (see page 609).
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.
Related topic
Email engine service failover in a server group (see page 1243)
BMC Remedy Single Sign-On architecture

BMC Remedy Single Sign-On (Remedy SSO) is an authentication system that supports SAMLv2
and BMC Remedy AR System many authentication protocols and provides single sign-on and
single sign-off for users of BMC products. Remedy SSO allows users to present credentials only
once for authentication and subsequently be automatically authenticated by every BMC product
that is integrated into the system.
You should install the Remedy SSO server and configure it with an authentication server such as
SAML or BMC Remedy AR System. Remedy SSO supports authentication with traditional system
such as Active Directory through SAML authentication. You can deploy the web application on the
same infrastructure as the AR Remedy Mid Tier. BMC products such as Remedy ITSM, BMC
MyIT, BMC Analytics for Business Service Management (BSM) use Remedy SSO agents that
redirect unauthenticated user requests to the Remedy SSO web application. BMC Remedy SSO
can provide SAML based authentication, where the Remedy SSO web application acts as a SAML
service provider. It redirects the login requests to the SAML identity provider.
The Remedy SSO web application is light weight and easier to deploy, configure, and maintain. It
can be deployed in the failover cluster which allows adding or removing the nodes easily on
demand. Remedy SSO persists user sessions in a database instance sharing sessions between all

nodes. Remedy SSO supports Microsoft SQL and Oracle database. The existing BMC AR System
database infrastructure can be used to leverage BMC products deployment and decrease
maintenance cost.
Architecture of Remedy SSO
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.

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 (see page 181)

Application programmer responsibilities (see page )
Developer responsibilities (see page 181)
End user responsibilities (see page 181)

Security administrator responsibilities (see page 181)
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
Managing user accesses for single sign-on, which includes managing server configuration,
authentication mechanisms, and multiple realms.

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
(see page 183) to understand any issues you might encounter.
Goal Instructions
Plan your BMC Remedy AR System installation. Learn about Available BMC Remedy
the available features and configuration types. AR System features and
configurations (see page
183)
Learn the available paths to install or upgrade. Installation and upgrade

paths (see page 188)
Learn about the BSM Reference Stack and BSM BSM environment
Interoperability programs that provide information about recommendations (see
certified environments in which you should install BMC page 200)
Remedy Action Request System.
Learn about the performance benchmarks and tuning for BMC Performance
Remedy AR System. benchmarking and tuning
in the BMC Remedy ITSM
Deployment space.
Learn the hardware and software requirements for installing System requirements (see
and running BMC Remedy AR System page 208)
Plan for securing your applications through encryption and Security

other methods.
Learn about what languages are supported and what Language information (see
considerations you should know when installing languages. page 230)
Learn about the standards followed by AR System server and BMC Remedy AR System
BMC Remedy Mid Tier. standards (see page 234)
Learn about how IPv6 is supported in BMC Remedy AR Support for IPv6 (see page
System. 236)
Available BMC Remedy AR System features

and configurations
BMC Remedy AR System consists of server and client features that you combine to create the
types of access you want to enable. Certain features are required for all BMC Remedy AR System
installations, while other features are optional. Planning is the key to a successful installation.

BMC Remedy AR System has a flexible and scalable architecture, and can be configured
depending on current and future needs.
BMC Remedy AR System requires several compatible features to function correctly. See
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation to check if your
current features are compatible with the BMC Remedy AR System version you are using.
This topic discusses the available features and configurations for BMC Remedy AR System:
Features you can install (see page 184)

BMC Remedy AR System server (see page 184)
BMC Remedy Mid Tier (see page 185)
BMC Remedy Email Engine (see page 185)
BMC Remedy Approval Server (see page 186)
Assignment Engine (see page 186)
Flashboards (see page 186)
BMC Remedy Developer Studio (see page 186)
BMC Remedy Data Import (see page 186)
BMC Atrium Integrator Engine (see page 186)
BMC Atrium Integrator (see page 187)
Configuration Types (see page 187)
Extending configuration to multiple servers (see page 187)
Extending configuration to the Web (see page 188)
Extending configuration to include email access (see page 188)
Sizing factors and scalability (see page 188)
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 page 2019).
See also BMC Remedy AR System functional components (see page 138).
BMC Remedy AR System can be installed with Microsoft SQL Server database or Oracle
database. 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 (see
page 2019).
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 (see page 160).
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 (see page 1457).
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 (see page 1419).
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

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 Engine

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

BMC Atrium Integration Engine is being replaced with a new offering called BMC Atrium
Integrator (see page 187). The currently available BMC Atrium Core version 8.1 will be
the last release that includes BMC Atrium Integration Engine. No new versions (major or
minor) of BMC Atrium Integration Engine will be released after 8.1. For more information
see, Statement of direction for the end of life of BMC Atrium Integration Engine.
BMC Atrium Integrator

BMC Atrium Integrator 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 can be installed on Microsoft Windows only.
Configuration Types
The following sections show the required and optional features in sample configurations. These
sample configurations do not demonstrate all possibilities. BMC Remedy AR System is flexible,
adaptable, and scalable, so you can mix and match features as needed.
Note
The sample configurations shown in this section do not represent all possible
combinations. Configurations are also flexible; you can change your configuration any
time.
Extending configuration to multiple servers

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

Client computers require a supported browser and Internet or intranet access for the mid tier
computer to access BMC Remedy AR System.
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 (see page 1457).
Sizing factors and scalability

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

For information about installing or upgrading BMC Remedy AR System, see the following topic
from the BMC Remedy ITSM 9.0 Deployment online documentation:
For fresh installation, see Installing .

For various upgrade paths and the upgrade process, see Upgrading .

This section provides the following information:
Planning a server group installation (see page 189)

Planning BMC Remedy AR System installation in an enterprise environment (see page 198)
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 (see page 189)

Server roles (see page 191)
Example configurations (see page 193)
Understanding server group naming (see page 196)
Planning where software is installed in server groups (see page 197)
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 (see page 489)
and Using a load balancer with server groups (see page 492).
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 (see page 345), 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 (see page 345).
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 (see page 345), 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 the same
computer.
Simple server group example

Complex example
A more complex server group implementation contains three or more AR System servers. In this
example we are using four AR System servers. It is still recommended to install all Remedy
products on each server, but it is not required. However, each application or component should be
installed on at least two servers so that failover can be provided.
Again, the first server installed should be configured to be the primary administration server. Then,
using the AR System Server Group Operation Ranking form (see page 345), 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 all the servers so that failover is possible. The FTS feature should
be installed on each server. It is also recommended that the FTS collection directory (location
where the search index files are stored) and FTS configuration directory (location where the search
configuration files are stored) be located on the same computer.
Related topics
Configuring server groups (see page 342)
Understanding server group naming

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

All AR System servers in a group must have the same server name parameter. This is specified in
the Administration Console as the Server Name Alias field. If your server group uses a load
balancer, the common server name parameter must be the same as the short DNS name of the
load balancer.
Note
Make sure that you use a name that will be translated to the IP address of the load
balancer. So, either the DNS should resolve the name or you must map the name in etc
/hosts file.
Clients can, therefore, be directed to the load balancer by using the server name parameter.
Note

If the server name alias setting is not the same as the load balancer short DNS name,
ARTask email attachments generated by the server might not work. When generating an
ARTask attachment, the server generates a reference to itself by using the server name
parameter with the domain name appended. Clients opening the ARTask will then use
the fully qualified domain name to be routed to the server group through the load
balancer.
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: svr_grp_tst3
IP-Name: svr_grp_tst3.svgroup.com
IP-Name: svr_grp_tst3.test.svgroup.com
IP-Name: 92.163.169.2
Other Info Needed:

Server-Name (resolves to the load balancer name): RemedyServerGroup
Domain-Name: test.svgroup.com
Planning BMC Remedy AR System installation in an

enterprise environment
The following table helps you plan your BMC Remedy AR System implementation in an enterprise
environment. Each link in the column leads you to key information about the component such as;
knowledge of common issues that you might encounter, actions that you should avoid, security
considerations, and third-party for your enterprise setup.
Topic AR System Mid tier Email Engine Assignment Approval BMC Atrium
Server Engine Server CMDB
Installing See Installing section from the BMC Remedy ITSM 9.0 Deployment online documentation.
Security Security Security Securing Configuring Security Security

considerations considerations incoming and the considerations considerations
for BMC for BMC Remedy outgoing email Assignment for BMC for BMC
Remedy AR AR System Engine Remedy AR Remedy AR
System System System
Access control Access control
User Specifying
authentication internal and
external
authentication
Scalability and AR System

high availability server
multithread
architecture
Load Balancing Using a load BMC Remedy Load

balancer with Mid Tier balancing with
server groups recommendations Email Engine

Distributed Distributed
deployment operations
introduction
Where to integrate Integration Integration Integrating the Integrating Integrating with

BMC Remedy AR technologies capabilities Assignment Approval CMDB
System Engine into an Server with an
application application
Web servers and Preparing your

JSP/servlet web server
engines
Proxy servers Proxy server and

load balancer
settings
Single sign-on Single sign-on

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

tuning tuning tuning Email Engine performance
for maximum for Approval
performance Server
Standards BMC Remedy BMC Remedy

AR System AR System
standards standards
Internationalization Language Language

and localization information information
Accessibility (508) Section 508

rules for
application
designers
Common Troubleshooting
problems and tips issues with
BMC Atrium
CMDB
Licensing Licensing Working with

Assignment sample users
Engine
Import and Reconciling data

reconciliation
Links to federated
systems

Configuring
federated data
in BMC Atrium
CMDB
Making changes Process

to classes or overview for
attributes creating or
modifying
classes
Collecting Gathering Collecting BMC Collecting Collecting Collecting Collecting BMC

information for information for Remedy Mid Tier BMC Remedy BMC Remedy BMC Remedy Atrium CMDB
support support information Email Engine Assignment Approval information
information Engine Server
information information
BSM environment recommendations

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

Atrium products (see page 201)

Cloud Lifecycle Management products (see page 202)
Service Operations - Application Performance Management products (see page 202)
Service Operations - Data Center Automation products (see page 203)
Service Operations - Proactive Operations products (see page 204)
Service Support products (see page 205)
Mainframe integrations (see page 206)
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
Core: common user, programmatic, and reporting interfaces to accelerate attainment of BSM.
BMC BMC Atrium CMDB stores information about the configuration items (CIs) in
Atrium your IT environment and the relationships between them. Data consumers such
CMDB as the BMC Remedy Asset Management product read data from the production
BMC dataset.
Atrium The BMC Atrium Integration Engine (AIE) product enables you to transfer data
Integrator between an external datastore and BMC Atrium CMDB or the BMC Remedy
Product Action Request System product.
Catalog The Product Catalog provides a normalized reference of software, hardware,
Service and other types of products and their characteristics that enhance the accuracy
Catalog of BMC Discovery products by uniquely identifying a product regardless of
Atrium installed name or location.
Web
Services
BMC Remedy 8.0 Enables the building of powerful business workflow applications which can
Action Request automatically track anything that is important to the processes in your enterprise.
System Companies use AR System to track such diverse items as stock trades, benefits data,
inventory assets, spare parts, and order fulfillment. A common use of AR System is to
automate the internal help desk.
BMC Atrium 7.6.02 1 SP 4 Delivers workflow-based process templates, with which customers can rapidly adapt
Orchestrator (see page and deploy functional design to ensure consistent and appropriate, policy-based
Platform ) response across the enterprise.
BMC Atrium 20.12.03

Orchestrator
Content

BMC Atrium
Solution or Product Version Service Function
suite name pack or
patch
BMC BMC 7.6.05.002 Hotfix Provides out-of-the-box interactive reporting and analysis that enables
Dashboards Analytics for technical and non-technical users to quickly examine data for trends
and Business and details associated with how IT is supporting business services and
Analytics Service goals.
Suite Management
BMC Atrium BMC Atrium 8.3.2.2 Provides an automated method for discovering, cataloging, and
Discovery Discovery maintaining a company's configuration data.
and and
Dependency Dependency
Mapping Mapping
BMC BMC 7.7 7.6.03 Provides highly interactive, timely access to key service support metrics
Dashboards Dashboards 7.6.03 Hotfix 9 to help IT management optimize decisions and accelerate the
and for Business alignment of IT with business goals.
Analytics Service
Suite Management
BMC BMC Service 8.0 Enables a service provider, such as an IT organization, a customer
Remedy IT Level support group, or an external service provider, to formally document the
Service Management needs of its customers or lines of business by using service level
Management agreements, and to provide the correct level of service to meet those
needs.
BMC BMC IT 8.0 Provides IT leaders visibility into costs, activities, assets, resources,
Remedy IT Business and suppliers to effectively manage the IT business and ensure
Service Management business alignment.
Management
BMC Cloud Lifecycle Management

Solution or Product Version Service Function
suite name pack or
patch
BMC Cloud BMC Cloud 3.0 SP1 + Provides a complete solution for establishing a cloud environment,
Lifecycle Lifecycle hotfix including a Service Catalog that defines service offerings, a self-service
Management Management console for procuring resources, and 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

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

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

Solution Product Version Service Function

or suite name pack or
patch
BMC BMC 8.2 SP 1 A web-based reporting and analytics tool, used together with the BMC
BladeLogic BladeLogic BladeLogic Network Automation solution to provide extensive reporting
Automation Decision capabilities based on the network devices you manage.
Suite Support for
Network
Automation
BMC BMC 8.2 SP 1 A web-based reporting application that provides extensive report capabilities
BladeLogic BladeLogic related to your data center servers that are managed by BMC BladeLogic.
Automation Decision BMC Service Automation Reporting and Analytics uses rich data warehouse
Suite Support for schema and dimensional modeling principles to access and report on
Server historical data captured by BMC BladeLogic.
Automation
BMC BMC 8.2 SP 1 Enables integration between BMC BladeLogic and Atrium components.
BladeLogic BladeLogic
Automation Integration
Suite with Atrium
8.2.01
BMC BMC 8.2.02 Manages change, configuration and compliance of network assets.
BladeLogic BladeLogic
Automation Network
Suite Automation
8.2.01
BMC BMC 8.2 SP 1 Acts as a platform for the management, control and enforcement of
BladeLogic BladeLogic configuration changes in the data center.
Automation Server
Suite Automation
8.2.01
2 8.2.00.001 is required if using BMC BladeLogic Client Automation for discovery for software license management use
cases.
Service Operations - Proactive Operations

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

Management suite.


suite Pack
or
Patch
BMC Agent, KM:

ProactiveNet 8.6 (7.5.62)
Performance BMC
Management PATROL
Consoles
and
Infrastructure
7.8.12
BMC
PATROL for
Servers
9.11.00
BMC BMC ProactiveNet 9.0 A real-time analytics solution that detects performance
ProactiveNet Core abnormalities in the IT environment, delivers early warning of
Performance BMC ProactiveNet degrading performance, and reduces time from issue detection to
Management Performance resolution. This early warning is delivered by Intelligent Events that
Management result from analyzing and correlating data across the monitored IT
Reporting infrastructure, speeding the ability to detect abnormal trends before
end users and mission critical applications are impacted. It also
provides the users with views, detailed graph displays, reports and
other tools for diagnosing performance issues.
BMC BMC Transaction 4.1 Enables you to manage the performance and reliability of your
ProactiveNet Management worldwide applications to measure site health based on end-user
Performance Application experience metrics, such as availability, accuracy, and
Management Response Time, performance.
either Infrastructure
Edition or Service
Level Edition
BMC Integration for BMC 9.0 Patch 1 Provides the integration from certain Service Assurance products to
ProactiveNet Remedy Service BMC Remedy IT Service Management.
Performance Desk
Management
Service Support
suite Pack
or
Patch
BMC BMC Remedy IT Service 8.0 The BMC Remedy Asset Management application lets IT
Remedy IT Management: professionals track and manage enterprise CIs - and their
Service changing relationships - throughout the entire CI lifecycle.
Management BMC Remedy
Suite Asset Management BMC Remedy Change Management provides IT
BMC Remedy organizations with the ability to manage changes by enabling
Change them to assess impact, risk, and resource requirements, and
Management then create plans and automate approval functions for
implementing changes.


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

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- Oracle Enterprise Edition 11g R1 (64-
bit) bit)
Application Tomcat 6.0.26 (64-bit) Tomcat 6.0.26 (64-bit)

server
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* (see page 207) JDK/JRE 1.6.0_20* (see page 207)
*see Oracle critical patch update notice (see page 207)
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
Related topics
System requirements (see page 208)
System requirements
See the topic Reviewing system requirements from the BMC Remedy ITSM Deployment online
documentation.
Security
The following topics contain information and instructions on BMC Remedy Action Request System
security planning:
Security architecture (see page 208)

Security considerations for BMC Remedy AR System (see page 210)
General security guidelines (see page 213)
BMC Remedy Encryption Security options (see page 220)
Security policy impact on client-server communication (see page 221)
BMC Remedy Encryption Security compatibility (see page 222)
BMC Remedy Encryption Security modifications to the JRE (see page 222)
WhiteHat Sentinel PE security penetration testing (see page 223)
Security architecture
This topic describes the BMC Remedy AR System security architecture.
Note
The IT environment and network infrastructure in which your BMC Remedy AR System
runs must be properly secured and include standard IT network security tools and
systems such as firewalls and intrusion detection systems (IDS).
System architecture
The BMC Remedy AR System architecture is multi-tiered; it consists of a Presentation layer, a
Logic layer, and a Data layer as shown here.

BMC Remedy AR System security architecture diagram

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 Compatibility
matrix in the BMC Remedy ITSM Deployment online documentation).
Logic layer
The Logic layer includes instances of a mid tier, a JavaServer Pages (JSP) engine, a web server,
and the BMC Remedy AR System server. The JSP engine and accompanying servlets provide
dynamically generated HTML and XML documents in response to web client requests. The mid tier
installer includes and can automatically install a bundled version of the Tomcat web server.
The mid tier translates client requires, interprets responses from the BMC Remedy AR System
server, handles web service requests, and runs server-side processes that present BMC Remedy
AR System functionality to the client from the BMC Remedy AR System server. The server
executes workflow and business logic that define all BMC Remedy AR System applications.
Because all BMC Remedy AR System clients are API-based, turning on encryption ensures that all
interactions with the server are encrypted.
Data layer
The Data layer consists of one or more databases, which perform data storage and retrieval
functions. The BMC Remedy AR System server connects to the Data layer using database client
API libraries. The server can work with the database encryption libraries used to protect data that
is transmitted between the server and database.

Security considerations for BMC Remedy AR System

When planning an enterprise setup, consult the following topics for security guidelines on the BMC
Remedy Action Request System (AR System) components:
BMC Remedy AR System security (see page 210)

Mid tier security (see page 211)
Approval server security (see page 213)
BMC Atrium CMDB security (see page 213)
Email Engine and Assignment Engine security (see page 213)
Additional Information (see page 213)
BMC Remedy AR System security

Security is an important consideration for AR System. The AR System server addresses security
through:
Access control (see page 1273) — Protects AR System data.

BMC Remedy Encryption Security (see page 220) — 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 (see page 257) and BMC Remedy
AR System configuration files (see page 1064).
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 (see page 1310).
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 in BMC Remedy
ITSM Deployment online documentation

Mid tier security

The mid tier provides a secure environment by encrypting sensitive data. All passwords are stored
in configuration files as encrypted strings. For the web server, you must add any additional security
if required.
Important
BMC recommends to use a secure socket layer (SSL) or HTTPS connection to encrypt
the data between the web server and the browser client.
Enabling SSL can impact performance due to the extra overhead required to encrypt and decrypt
on both ends.
Note
You can now log on to BMC Remedy Mid Tier using only HTTP POST requests.
Use BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium
Security to encrypt communication between AR System components, including the mid tier.
When securing the mid tier, consider these tips about:
SSL (see page 211)

XSS (see page 212)
WebDAV (see page 212)
HTTP transport (see page 212)
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.
BMC Remedy security certification (see page 223)

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:
BMC Remedy security certification (see page 223)
BMC Remedy Encryption Security options (see page 220)
Security policy impact on client-server communication (see page 221)
BMC Remedy Encryption Security compatibility (see page 222)
Installing BMC Remedy Encryption Security in BMC Remedy ITSM Deployment
online documentation.
Configuring BMC Remedy Encryption Security (see page 689)
Troubleshooting encryption security (see page 4751)
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 (see page 684
).
For information on Assignment Engine security, see Configuring the Assignment Engine server
settings (see page 653).
Additional Information
For more information on security guidelines, see the blog Choose your request methods carefully
shared on BMC Communities.
General security guidelines

This topic presents security guidelines to consider when using BMC Remedy Action Request
System (BMC Remedy AR System).
What security components does BMC Remedy AR System provide?
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.
BMC Remedy AR System uses transport layer security and digital signatures to perform
end-to-end validation after a connection is made.
What should I do to encrypt the traffic?
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.
How do I prevent Cross-Site Request Forgery (CSRF)?
Using this technique, attackers make victims perform actions that they did not intend to, such as
logging out, purchasing items, or other functions provided by the vulnerable website. The user's
browser is tricked into issuing a command to a vulnerable web application.
The vulnerability is caused by browsers automatically including user authentication data such as a
session ID, IP address, or Microsoft Windows domain credentials with each request.
The AR System disables web server scripting in the mid tier. The processes that run on the AR
System server is restricted by the AR System permissions model, and are restricted to specific
directories on the server.
What steps should I follow to install Tomcat securely?
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
How do I prevent cross-site tracing (XST)?
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 (see page
3303).
What procedure should I use to mark all the cookies as secure?

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.
How do I enable Mid Tier security for 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
What should I do prevent the Mid Tier from allowing a user to submit a URL containing a 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.
What should I do to prevent frame phishing vulnerabilities in Mid tier?
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.
Is the data secure within BMC Remedy AR System server?
When encryption is employed, unsafe key generation, non-rotating keys, and weak algorithm
usage is common. The use of weak or unsalted hashes to protect passwords is also common.
All sensitive data is encrypted within AR System. All communication between the web browser and
the web server can be encrypted using HTTPS. All communication between the web server and
the AR System server can be encrypted using API encryption.
The Mid Tier access is prevented by some security software. What should I do?
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.

How do I restrict goto URL to a specified list?
You can add an inclusion list of URLs to be redirected to when you log on to the mid tier and when
you log out of the mid tier. An inclusion list of URLs is allowed in the goto request parameter of
LoginServlet and LogoutServlet so that the user is automatically redirected to the specified URL.
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.
How do I secure the file extension for my attachments?
To prevent XSS attacks using some attachments, mid tier allows you to add an inclusion list of
supported file extensions for attachment.
To add an inclusion list, add the following property in the <midTierInstallDirectory>/WEB-INF

/classes/config.properties file:
arsystem.inclusion_attachment_extension=<Comma seperated list of File

extensions>
How do I ensure my organization is HIPAA compliant?
HIPAA Compliance is about the business itself and the processes within that organization. A
software product itself cannot be HIPAA compliant, but can support the HIPAA compliance
goal of an organization. BMC Remedy AR System provides number of features that support
customers in building HIPAA compliant processes. For example, forced (re-)authentication
for approval and electronic signature.
When used correctly, BMC Remedy AR System and applications built on BMC Remedy AR
System, like, BMC Remedy IT Service Management (ITSM), provide the necessary
capabilities for a business to meet HIPAA guidelines.
How do I use the RSS Feed Security?
There is no standardization around using an authenticated RSS feed with a RSS feed client.
The subscription to RSS feed in BMC Remedy AR System requires an additional factor of
security, as it asks for authentication credentials and encrypts them using RSA Asymmetric
cryptography as part of the RSS feed URL. For more information, see Subscribing to RSS
feeds (see page 2212).
When the user accesses an RSS feed using an RSS feed client, the encrypted credentials
from the RSS feed URL are used by BMC Remedy AR System server for authenticating the
user and querying the data requested based on the user's permissions.
Note

The end user needs to ensure that no unauthorized person can get access his RSS Feed
URL.
How do I prevent unauthorized access to the SessionID cookies?
Cookies carrying sensitive information can be marked as HTTPOnly. The browsers supporting this
attribute prevent access to such Cookies by client-side script (JavaScript).
The SessionID cookie (JSessionID) is the only cookie used by BMC Remedy Mid Tier that carries
information about user's SessionID. By default, all SessionID cookies are marked as HTTPOnly to
prevent unauthorized access to the SessionID cookies.
What is the TLS POODLE issue with the load balancers?
There is a newly reported TLS POODLE vulnerability. For more information, see https://community.
qualys.com/blogs/securitylabs/2014/12/08/poodle-bites-tls. There is a new critical vulnerability
reported for this issue on F5 load balancers. It appears that F5 load balancer is vulnerable to this
TLS POODLE vulnerability. For more information, see https://cve.mitre.org/cgi-bin/cvename.cgi?
name=CVE-2014-8730.
It is important to apply the F5 hot fix if you are using a F5 load balancer. If you are using any other
load balancer, confirm with your load balancer vendor if it suffers from the TLS POODLE
vulnerability and get a hotfix for the issue. For more information, see https://www.imperialviolet.org
/2014/12/08/poodleagain.html which lists other load balancer vendors affected by this vulnerability.
Use the SSL Labs SSL Server Test tool https://www.ssllabs.com/ssltest/ to check your server for
SSL related vulnerabilities.
How do I check for the impact of SSL 3.0 POODLE Security vulnerability?
BMC provides information on the products that allow SSL 3.0 connections and are therefore
affected by the SSL 3.0 CVE-2014-3566 vulnerability. for more information see SSL 3.0 “POODLE”
Security Vulnerability -- CVE-2014-3566.
Related topic
Cookies used by BMC Remedy Mid Tier (see page 467)
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 (see page 66).
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 client
encryption without
encryption
8.1 Optional (Default) Encrypted if client Unencrypted (Default) Encrypted if Unencrypted Unencrypted
encryp-tion level matches client encryp-tion level
server configuration OR matches server
Unencrypted 1 configuration OR
Unencrypted 1
Required (Default) Encrypted if client None (Default) Encrypted if None None

(FIPS not encryp-tion level matches client encryp-tion level
enabled 2 server configuration OR matches server
) None configuration OR None
Required (Default) Encrypted if client None None None None

(FIPS encryp-tion level matches
enabled 2 server configuration OR
) None
Disabled Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted
5.1.2- Optional (Default) Encrypted if client Unencrypted (Default) Encrypted if Unencrypted Unencrypted
7.1.00 encryp-tion level matches client encryp-tion level
Unencrypted 1 configuration OR
Unencrypted 1
Required (Default) Encrypted if client None (Default) Encrypted if None None

encryp-tion level matches client encryp-tion level
None configuration OR None
Disabled Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted
Pre- NA Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted

5.1.2
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 Activating FIPS compliance (see page 695) and FIPS encryption
options in BMC Remedy ITSM Deployment online documentation.
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 Compatibility
matrix in BMC Remedy ITSM Deployment online documentation.
BMC Remedy Encryption Security modifications to the JRE

When you install BMC Remedy Encryption Performance Security or BMC Remedy Encryption
Premium Security on Java-based components, the JDK JRE and public JRE directories that you
specify during installation are modified as follows:
These providers are added:

RSA Crypto-J 4.0 FIPS-140

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.
WhiteHat Sentinel PE security penetration testing
BMC Remedy ITSM 9.1 and BMC Remedy AR System 9.1 use the WhiteHat Sentinel Premium
Edition (WhiteHat Sentinel PE) service, a dynamic application security tool (DAST), for security
penetration testing. By performing security penetration testing, BMC can identify whether
applications are vulnerable to web attacks and implement the required countermeasures to reduce
vulnerabilities.
As of December 13, 2015, BMC Remedy ITSM 9.1 and BMC Remedy AR System 9.1 do not have
any security penetration vulnerabilities.
This topic contains the following information:
WhiteHat security vulnerability tests (see page 224)

Whitehat PCI Compliance Testing (see page 224)
Whitehat reports (see page 225)
Test environment (see page 225)
Changes required for on-premise and BMC Remedy OnDemand environments (see page
226)
Configuring Apache Tomcat settings to disable directory listings (see page 226)
Creating an SSL profile on the reverse proxy to disable RC4 ciphers (see page 227)
Restricting attachments by using Attachment Security (see page 227)
Enforcing the default password policy in BMC Remedy AR System (see page 228)
F5 Load Balancer hotfix (see page 228)
BMC Remedy Mid Tier security settings (see page 228)

Enabling secure cookie in BMC Remedy SSO (see page 230)
Note
For BMC Remedy ITSM 9.1 and BMC Remedy AR System 9.1, BMC schedules
automated security scans with WhiteHat Security that are run on the SaaS-based
WhiteHat Sentinel platform. Automated scans are augmented by manual penetration
tests performed by WhiteHat security experts. After the tests are completed, BMC
receives vulnerability assessment reports. For more information about WhiteHat Sentinel,
see https://www.whitehatsec.com/sentinel_services/benefits.html.
For BMC Remedy ITSM 9.1 and BMC Remedy AR System 9.1, security penetration tests were
performed using a BMC Remedy OnDemand instance deployed in the following environment:
WhiteHat security vulnerability tests

As of December 13, 2015, WhiteHat Security has run 242 automated security scans of BMC
Remedy AR System 9.1 and BMC Remedy ITSM 9.1. Whitehat Security performs manual
testing by further exploring areas found during the automated testing.
WhiteHat Security employs the following types of tests during the security testing:
Authentication tests (brute force, insufficient authentication, weak password recovery, cross-
site request forgery, credential/session prediction, insufficient authorization, insufficient
session expiration, session fixation)
Client-side attack tests (content spoofing, cross-site scripting, HTTP response splitting)
Command execution tests (buffer overflow, format string attack, LDAP injection, OS
commanding, SQL injection, server-side include injection, XPath injection)
Information disclosure tests (directory indexing, information leakage, path traversal,
predictable resource location)
Logical attack tests (abuse of functionality, denial of service, insufficient anti-automation,
insufficient process validation)
For more information about WhiteHat Security, see the website security statement for WhiteHat
Security.
Whitehat PCI Compliance Testing

Whitehat also test for compliance with the Payment Card Industry Data Security Standard (PCI-
DSS Version 3.0), which includes requirements that web applications be built to secure coding
guidelines and that applications be subject to routine vulnerability checks. The following categories
of PCI tests are employed:
Injection flaws
Buffer overflow

Insecure Cryptographic Storage

Insecure Communications
Improper Error Handling
Cross Site Scripting
Improper Access Control
Cross Site Request Forgery
Broken Authentication and Session Management
Whitehat reports
For more information about the WhiteHat Sentinel PE tests that were used and the results, which
are zero technical and business logic vulnerabilities, see the following reports:
WhiteHat Security Audit Report

WhiteHat Security PCI Compliance Report
BMC and Whitehat Security are continually running tests as BMC augments the environment or
adds new security tests.
Test environment
Component Server specifications VM Operating system
used?
BMC Remedy Mid Tier 9.1 Yes CentOS release 6.5 (Final)
2 CPUs (Intel® Xeon® CPU E7 4870 @
2.40 GHz)
8 GB RAM
25 GB drive for BMC Remedy
applications
15 GB drive for paging
BMC Remedy AR System Yes Microsoft Windows Server 2008 R2

9.1 2 CPUs (Intel® Xeon® CPU E7 4870 @ (64-bit)
2.40 GHz)
BMC Remedy ITSM 9.1 8 GB RAM
39.9 GB drive for BMC Remedy
applications
BMC Remedy Single Sign- Yes CentOS release 6.5 (Final)

on 9.1 2 CPUs (Intel® Xeon® CPU E7- 4870 @
2.40GHz
8 GB RAM
BMC Remedy Smart Yes CentOS release 6.2 (Final)

Reporting 9.1 2 CPUs (Intel Xeon CPU E7 4870 @
2.40 GHZ)
16 GB RAM
25 GB drive for BMC Remedy
Applications

Component Server specifications VM Operating system

used?
Changes required for on-premise and BMC Remedy OnDemand environments

The following changes are required for on-premise and BMC Remedy OnDemand environments to
achieve zero technical and business logic vulnerabilities in BMC Remedy 9.1 and BMC Remedy
AR System 9.1:
Configuring Apache Tomcat settings to disable directory listings (see page 226)
Creating an SSL profile on the reverse proxy to disable RC4 ciphers (see page 227)
Restricting attachments by using Attachment Security (see page 227)
Enforcing the default password policy in BMC Remedy AR System (see page 228)
F5 Load Balancer hotfix (see page 228)
BMC Remedy Mid Tier security settings (see page 228)
Enabling secure cookie in BMC Remedy SSO (see page 230)
Configuring Apache Tomcat settings to disable directory listings

To prevent a security vulnerability from directory listings, BMC used the following procedure to
disable directory listings on the Tomcat web server hosting BMC Remedy Mid Tier:
1. Stop the Tomcat server.

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

Creating an SSL profile on the reverse proxy to disable RC4 ciphers

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

BMC used the Attachment Security feature. This feature helps to prevent users from uploading
malicious attachments and viewing them in the BMC Remedy Mid Tier. BMC defined the following
attachment extensions as the only attachment extensions allowed for attachment uploads:
.txt
.png
.jpg
To restrict attachments, BMC used the following procedure to make the changes to the
Attachment Security tab of the AR System Administration: Server Information form:
1. Select the following options:

Allow attachments with following extensions option in the Attachment criteria
field
Allow display of attachments with the following extensions option in the Display
criteria field
2.
2. Define the list of attachment extensions (.txt, .png, .jpg) in the Comma separated list of
limit extensions and Comma separated list of display extensions fields.
3. Click Apply.
For additional information about how to restrict attachments, see Setting security restrictions on file
uploads (see page 317).
The following image shows the changes made to the Attachment Security tab.
AR System Administration: Server Information form — Attachment Security tab
Enforcing the default password policy in BMC Remedy AR System

BMC Remedy AR System uses an MD5 hash of passwords stored in the database, ensuring that
passwords cannot be retrieved. To enable and configure a password policy, refer to the topic
Enforcing a password policy introduction (see page 1310). For the BMC WhiteHat security testing,
the default password policy was enabled.
F5 Load Balancer hotfix

In certain F5 Load Balancers, an active attacker may be able to recover plain text, such as
authentication cookies, from a TLS1.x connection. The solution is to upgrade the F5 Local Traffic
Manager (LTM) to the version 11.6 hotfix. Refer to the F5 support document https://support.f5.com
/kb/en-us/solutions/public/15000/800/sol15882.html for additional information.
BMC Remedy Mid Tier security settings

The following table lists the BMC Remedy Mid Tier settings used for Whitehat security testing:

Parameter Setting
Use Post for Added following parameter in midtier/WEB-INF/classes/config.properties

Backchannel calls
arsystem.xmlhttp.get=false
Plugin XSS Security Added following parameter in midtier/WEB-INF/classes/config.properties:

Check
arsystem.plugin_securitycheck=true
Turn on Uncommented following from midtier/WEB-INF/web.xml:

SecureCookieFilter
<filter>
<filterclass>com.remedy.arsys.stubs.SecureCookieFilter</fliter-class>
</filter>
<filter-mapping>
</filter-mapping>
Turn on XSSFilter Uncommented following from midtier/WEB-INF/web.xml:
<filter>
<filter-class>com.remedy.arsys.stubs.XSSFilter</filter-class>
</filter>
<filter-mapping>
<url-pattern>/plugins/*</url-pattern>
</filter-mapping>
<filter-mapping>
<url-pattern>/pluginsignal/*</url-pattern>
</filter-mapping>
Turn Uncommented following from midtier/WEB-INF/web.xml:

on CLICKJACKFILTER
<filter>
<filter-name>CLICKJACKFILTER</filter-name>
<filter-class>com.remedy.arsys.support.ClickJackFilter</filter-class>
<init-param>
<param-name>mode</param-name>
<param-value>SAMEORIGIN</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CLICKJACKFILTER</filter-name>
</filter-mapping>

Enabling secure cookie in BMC Remedy SSO

To enable the secure cookie in BMC Remedy SSO, perform the following:
1. Navigate to BMC Remedy SSO admin console > General > Advanced.
2. Select Enable Secured Cookie and click Save.
For more information, see Managing Server Configuration (see page 676).
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 (see
page 3181).
Topics include:
Supported languages and character encodings (see page 231)

Localized forms (see page 232)
Installing BMC Remedy AR System in an international environment: Oracle on UNIX (see
page 233)
BMC Remedy Email Engine internationalization support (see page 234)

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

BMC Remedy AR System server and the BMC Remedy Mid Tier adhere to the standards listed in
the following topics:

BMC Remedy AR System server standards

The AR System server provides encryption of information as it is passes over the wire. The
standard encryption provided by the AR System server is based on OpenSSL libraries
version 0.9.6m.
The AR System server provides an API that is based on ONCRPC.
AR System web services implementation is based on SOAP 1.1 and WSDL 1.1
specifications from W3C. SOAP 1.2 is supported for consuming web services only.
Security
Web service standards (see page 3432)
BMC Remedy Mid Tier standards

Software standards ensure desirable characteristics of products and services such as quality,
environmental friendliness, safety, reliability, efficiency and interchangeability. The International
Organization for Standardization (ISO) is a developer of international standards. BMC strives to
make sure that each release of the BMC Remedy Mid Tier adheres to current standards.
Remember these tips:
Use HTTP 1.1. (HTTP 1.0 is not supported.) Ensure that your browser uses HTTP 1.1 so
that the mid tier can take advantage of data compression, persistent connection, and chunk
transfer.
BMC supports any SSL version that is supported by each HTTP web server vendor listed on
the compatibility matrix.
The mid tier supports 32-bit and 64-bit version of Java runtime environment.
The following table lists standards supported by recent versions of the mid tier. See the
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation for potential
incompatibilities.
AR 7.5.00 AR 7.6.04 8.0 and later
HTTP 1.1 1.1 1.1

/HTTPS
HTML 4.0+ 4.0+ 4.0+
Java Script 1.3+ 1.3+ 1.3+
SOAP 1.1 or 1.1 or 1.1 or 1.2

1.2 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 5.0 or 5.0 or 6.0

6.0 6.0
Support for IPv6
Note
BMC Remedy AR System supports IPv6 for only version 8.1 and later releases.
BMC Remedy Action Request System supports Internet Protocol version 6 (IPv6) network
addresses. You can deploy BMC Remedy AR System servers in an IPv6 configured network and
make them accessible to clients on IPv4, IPv6, or both IPv4 and IPv6 (dual stack) configured
hosts.
IPv6 is an internet protocol that replaces IPv4. It expands the IP address space from 32-bit to 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:
Post-installation or post-upgrade considerations (see page 236)

Supported operating systems for IPv6 (see page 236)
Supported databases for IPv6 (see page 237)
IPv6 considerations with BMC Remedy AR System (see page 237)
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 in BMC Remedy ITSM Deployment online documentation.
Supported operating systems for IPv6

BMC Remedy AR System supports the following minimum operating systems for IPv6:
Windows 2008 (x64-bit only)

Red Hat Enterprise Linux 6.1 (x64 only)

Note
For Windows, Java SE 7 is required for IPv6.
For Windows 2008 and earlier, all 32-bit versions support only IPv4.
Supported databases for IPv6

BMC Remedy AR System supports the following minimum databases for IPv6:
Oracle 11g R2
Microsoft SQL Server 2008
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 (see page 2963).

Installing
For the latest installation information, see BMC Remedy ITSM 9.1 Deployment online
documentation (see page 238) .
About BMC Remedy ITSM Suite 9.1

Deployment online documentation
The following graphic illustrates scope and the contents of this online documentation.
The following table describes the contents of the different branches in this online documentation.
Branch Description
Planning the This section describes the deployment scenarios for the following new components:
deployment
Click here for a list of topics in this section
Planning BMC Remedy Smart Reporting deployment

Planning BMC Remedy shared service architecture
Preparing This section provides information about the preparation you must do before installing or upgrading any
component of the BMC Remedy ITSM Suite.
Click here for the list of topics in this section
Reviewing system requirements

Downloading the installation files
Obtaining BMC Remedy license keys
Preparing your database
Preparing the base platform
Preupgrade checks and configuration checks

Branch Description
Completing the planning spreadsheet
Installing This section provides information about the steps for performing a fresh installation.
Installing the platform components

Installing the application components
Installing offline documentation
Deploying BMC Remedy shared services
Upgrading This section provides information about the steps for performing an upgrade.
Interactive end-to-end steps depending on the base version:

Upgrading from version 8.1 and later
Upgrading from a version 7.6.04 or 8.0.xx
Upgrading from a version earlier than 7.6.04
Upgrading information the individual components in the BMC Remedy ITSM Suite
Upgrading the platform
Upgrading the applications
Detailed information of different stages within the upgrade process:
Restrictions after restoring the database on the upgrade server
Setting up upgrade servers
Capturing a snapshot of your current environment
Creating overlays
Adjusting customizations when upgrading
Reconciling AR customizations
Migrating customizations
Updating hard-coded server hostname references
Migrating delta data
Update to the multi-tenancy model
Post-upgrade activities
Upgrading secondary servers
User acceptance testing
Cutover activities
Go live activities
Troubleshooting This section provides information about troubleshooting the issues specific to install or upgrade.
Working with logs

Troubleshooting data and workflow import issues
Troubleshooting driver issues
Troubleshooting information for individual components in the BMC Remedy ITSM Suite
Troubleshooting BMC Remedy AR System issues
Troubleshooting BMC Atrium Core issues
Troubleshooting BMC Remedy ITSM issues
Troubleshooting Process Designer issues
Troubleshooting BMC Service Request Management issues
Troubleshooting BMC Service Level Management issues

Branch Description
Troubleshooting the multi-tenancy update


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 (see page 1059) section for additional configuration and administrative tasks, such
as setting up user accounts.
Goal Instructions
Logging on to various BMC Remedy AR System Logging on to the system (see

components page 242)
Managing BMC Remedy AR System licenses Working with BMC Remedy

AR System licenses (see page
243)
Configuring servers to work with BMC Remedy AR System Configuring AR System

Setting up a server group to provide fail-over protection Configuring server groups

(see page 342)
Configuring the BMC Remedy AR System cache BMC Remedy AR System

cache management (see page
369)
Presenting application data and interacting with the user BMC Remedy Mid Tier
by using the BMC Remedy Mid Tier configuration (see page 393)
Using a hardware load balancer to improve the scalability Configuring a hardware load
and availability of the BMC Remedy AR System balancer with BMC Remedy
AR System (see page 489)
Configuring Unicode database support to enable multiple Configuring a Unicode server

languages on a single AR System server (see page 511)
Monitor BMC Remedy AR System using the BMC Remedy BMC Remedy SNMP Agent
SNMP Agent configuration (see page 519)
Configuring BMC Remedy AR System servers for a Configuring BMC Remedy

distributed environment Distributed Server Option (see
page 535)
Configuring BMC Remedy AR System web and crystal Configuring reporting (see
reports for the end users page 561)
Configuring the Assignment Engine properties and starting Configuring the Assignment
and stopping the engine Engine server settings (see
page 653)
Configuring and managing process administrator Configuring the BMC Remedy

capabilities, configuring Approval Server to work with Approval Server (see page 595
flowcharts, and with a separate plug-in server instance )

Goal Instructions
Creating and configuring BMC Remedy Email Engine Configuring BMC Remedy
mailboxes and setting security options Email Engine (see page 604)
Manually changing the default behavior of flashboards by Configuring BMC Remedy

changing settings in the config.properties file, and Flashboards (see page 634)
configuring flashboards
Licensing and logging on to BMC Remedy Migrator Configuring BMC Remedy

Migrator (see page 647)
Securing various aspects of BMC Remedy AR System Securing BMC Remedy AR

System (see page 678)
Configuring BMC Remedy Encryption Security to protect Configuring BMC Remedy

data passing between the client and server Encryption Security (see page
689)
Learn about the storage and performance impacts of using Using Oracle CLOBs with
Oracle character large object (CLOB) storage in a BMC Remedy AR System
database table (see page 697)
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 (see page 1969)
BMC Remedy Developer Starting and logging on to BMC Remedy Developer Studio (see page 2255)
Studio
BMC Remedy Migrator Logging on to an AR System server using BMC Remedy Migrator (see page 2063)
BMC Remedy Mid Tier Logging on to the Mid Tier Configuration Tool (see page 428)
BMC Remedy Mid Tier URLs for opening forms and applications (see page 2963)
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 (see page 644).

Customize the cache behavior (see page 448).
Change the number of entries in a report (see page 562).
Configure the wait time for detecting a HOVER event (see page 2836).
Modify the wait cursor for actions when customizing views for forms (see page 3112) or turn
off the wait cursor (see page 3114).
Set up a mid tier server to use cache table statistics (see page 443).
Enable the HTTP TRACE function to return HTTP header information (see page 3303).
Working with BMC Remedy AR System

licenses
The following topics provide information about licensing BMC Remedy AR System:
Adding or removing licenses (see page 243)

Exporting or importing licenses (see page 245)
Displaying and Tracking server group license usage (see page 247)
Reviewing license usage (see page 250)
Generating a license usage report (see page 253)
Licensing for server groups (see page 254)
Adding or removing licenses

You can add or remove licenses, follow the given procedures.
Adding licenses (see page 243)

Removing licenses (see page 244)
Related Topics (see page 245)
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.
2. In the Add or Remove Licenses form, click Add New.
3.
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
Type the list.
Note: You can add only one entry for each license type except server licenses (multiple server licenses
are distinguished from each other by license keys). To increase or decrease the number of licenses
available for other license types, modify the existing entry.
Number 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 in BMC Remedy ITSM Deployment documentation.
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
Date 7.1.00 and later, only trial licenses expire.)
4. Click Save.
To add licenses by importing them

See Importing licenses (see page 245).
Removing licenses
To remove a BMC Remedy AR System license from a server, follow this procedure:
Licenses.
2. In the table at the top of the form, select the license to remove.
3. Do one of the following:
Click Delete, and then click OK in the confirmation message.
4. Set the Number of Licenses field to 0, and then click Save.
Note
Nonserver license removals take effect immediately. To remove a server license,

however, you must restart the server after removing the license.

Related Topics

Licensing for server groups (see page 254)
Exporting or importing licenses

You can use the Add or Remove Licenses form to export or import licenses.
Exporting licenses (see page 245)

Importing licenses (see page 245)
Exporting licenses
You can export license information in the Add or Remove Licenses form to a . lic file to create a
backup copy. You must export all the licenses, you cannot select specific licenses to export.
To export AR System licenses
Licenses.
2. Click Export Licenses to File.
3. In the Save Attachment dialog box, navigate to the directory in which to save the . lic file.
4. In the File name field, enter a name for the license file or accept the default (arsystem.lic).
5. Click Save.
Importing licenses
To import licenses from BMC Remedy AR System 7.x or 6.x. lic files into a BMC Remedy AR
System 7.1.00 or later server, use this procedure.
Notes
Except for AR Server licenses, license keys are not imported. In addition, expired
licenses are not imported.
In BMC Remedy AR System 7.1.00 or later, dedicated server licenses -provided for
common components such as the BMC Atrium Definitive Software Library or CMDB- are
not used. If you had a dedicated server license in a previous release, it is upgraded at no
cost to a full AR Server license when you import your licenses. In addition, licenses for
any applications associated with the dedicated server are automatically added to your
system.

To import AR System 7. x or 6. x licenses
Licenses.
2. Click Import Licenses from File.
3. In the Add Attachment dialog box, navigate to the location of the license ( .lic) file to import.
4. Select the file name to add it to the File name field.
5. Click Open.
6. When asked "Do you want to overwrite any matching licenses?," click one of these
buttons:
No — Merges the contents of the .licfile with the contents of the Add or Remove
Licenses form as follows:
When the form and the .lic file contain a matching license type, the entries for
that type are not imported from the .lic file.
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 .lic file 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 .lic
file. 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 (see page ).
7. In the confirmation message, click OK.
Related Topics

Displaying and Tracking server group license usage

The following topics provide information about the license usage forms and how to track license
usage:
AR System Current License Usage form (see page 247)

AR System Historical License Usage form (see page 248)
Recording data in the license usage forms (see page 249)
Tracking server group license usage (see page 249)
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, read, restricted-read)

Type
Note: AR System Current License Usage form tracks only fixed and floating licenses.
Server Server to which the license is applied

Name
Time Time that the user acquired the license

Acquired
Note

Field Description
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 (see page ).
To get a report about license usage, see Generating a license usage report (see page 253). 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 (see page 249).
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, read, read-restricted)
Note: AR System Historical License Usage form tracks only fixed and floating
licenses.
Time Acquired Time that the user acquired the license

Field Description
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 (see page 249).
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.
Even after the license tracking is enabled, AR System Current License Usage and AR
System Historical License Usage forms track only fixed and floating licenses.
To record data in the license usage forms
1. In the AR System Administration Console, click System > General > Server Information.
2. On the Configuration tab, select the Enable License Tracking option.
3. Save your changes.
BMC Remedy AR System immediately starts recording data in the license usage forms. You
do not need to restart the AR System server.
To stop recording data in the license usage forms

Clear the Enable License Tracking option, and save your change.
All data in the AR System Current License Usage form is lost when
The Enable License Tracking option is switched off.

A standalone server is stopped.
All servers in a server group are stopped.
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. For example, for
a user currently logged into the system, there is one main record, and for every server in the server
group the user is logged, there is one sub-record.

If the user acquires another license of the same type on another server in the group without
releasing the first license, the second license is recorded as another subrecord of the main record.
The same is true of all additional licenses of that type acquired while the main record has at least
one subrecord.
When the user logs out of the sessions from a server by releasing one of his licenses, its
subrecord for the license is deleted. When the last subrecord is deleted, it indicates that the user
has logged out and released all the licenses from the server, the main record is also deleted and
an entry for the entire session tracked by the main record is added to the AR System Historical
License Usage form.
Related Topics

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:
Reporting license usage within a date range (see page 252)

Verifying purchased licenses (see page 252)
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
Licenses.
2. In the Add or Remove Licenses form, click Generate License Usage Report.
3. Click the calendar icon next to the License Report Start Date field, and select a date from
the calendar.
The start time is 12:00:00 A.M. on the specified date.
4. Click the calendar icon next to the License Report End Date field, and select a date from
the calendar.
The end time is 11:59:59 P.M. on the specified date.

4.
Note
- If the selected start or end date exceeds the time period covered by the server,
the first or last date covered by the server is used instead. The time period
covered by the report is specified in the report header.
- Make sure that the time zone for BMC Remedy Mid Tier and BMC Remedy AR
System server is same, to map the start and the end date requested while
generating the License Usage Report. If the time zone for BMC Remedy Mid Tier
and BMC Remedy AR System server is different, the time zone for BMC Remedy
AR system server is considered.
5. Click Generate Report.

A message specifying the location of the ReportResult.csvfile appears. By default, the file
is stored in this directory:
(UNIX) ARSystemServerInstallDir/Db
(Windows) ARSystemServerInstallDir\ARServer\Db
6. Click OK.
The license usage report is displayed in a CSV-compatible viewer, such as Microsoft Excel.
Note
You can also use the produse.exe utility to generate a license usage report. See
Generating a license usage report (see page 253).
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 (see page 4761)).
Related Topics

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.
- Specifies the full or relative path to the output file. By default, the output file name is ReportResult.csv and is in this
o 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.
- 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
s is not specified, the report includes data from the beginning of the LicenseReport.txt file. If this parameter exceeds the
range covered by the LicenseReport.txt file, the range covered by the file is used instead, and that range is indicated in the
report header.
- Specifies the end date of the report in D/M/YYYY format. The end time is 12:00 P.M. on the specified date. If this parameter
e is not specified, the report includes data to the end of the LicenseReport.txt file. If this parameter exceeds the range
covered by the LicenseReport.txt file, the range covered by the file is used instead, and that range is indicated in the report
header.
- Backs up the current LicenseReport.txt file by renaming it LicenseReport- fileCreateDate- currentDate.txt and generating a
r new LicenseReport.txt file.
Note
You can also generate a license usage report from the Administration Console. See
Reviewing license usage (see page 251).
Related Topics
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 (see page 243).
All other license types, such as all types of Fixed and Floating user licenses and application
licenses, are stored in the database and are therefore shared by all servers in the server group.
You can add these other product licenses at any time. However, for all AR System servers, except
the first server, the license must be added prior to installing the server.
Related Topics


Tracking server group license usage (see page 249)
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 (see page 1060).
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 (see page
)
Always On Configures the options for Always On Logging feature. Setting Always On logging
Logging (see page 339)
Configuration Sets configuration options. Setting administrative options

(see page )
Connection Enables you to configure passwords used between the AR System server and Setting server passwords,
Settings its external subsystems. RPC options, and plug-in
timeouts (see page )
Currency Specifies currency types available in AR System. Setting currency types (see
Types page )
Database Displays information about the database that the selected server Setting database options (see
communicates with. You also define a database password and configuration page )
file location in this tab.
DSO Configures options for distributed operations. Configuring BMC Remedy

Distributed Server Option (see
page 535)
EA Sets parameters necessary for AR System to authenticate users to external

systems. Setting external
authentication options
(see page )
Configuring the AR
System server for
external authentication
(see page 260)

Tab Information See
Encryption Enables you to view and modify your AR System server's encryption Activating and deactivating
configuration. encryption security (see page
693)
Full Text Configures full text search (FTS) options. Configuring Full Text Search
Search (see page 546)
Licenses Displays the type and number of BMC Remedy AR System licenses on a Setting license options (see
server. You also set the Submitter Mode in this tab. page )
Log Files Enables the logging for various log files. You also set the log level in this tab. Setting log files options (see
page )
Log Filtering Enables you to apply restrictions on the AR System server logging, based on Configuring AR System server
one or more parameters. logging (see page 4359)
Platform Displays information about the platform on which the selected server is Setting platform options (see
running. page )
Ports and Configures BMC Remedy AR System to communicate with client tools,
Queues services, and other servers on the network. Displays information relevant to Setting ports and RPC
the user of the multiple threads in the AR System server. numbers (see page )
Configuring a server for
alerts (see page 259)
Defining queues and
configuring threads
(see page 298)
Server Sets the options for logging internal server changes. Setting server logging options
Events (see page )
Timeouts Sets various timeouts for the selected server. Setting timeout options (see
page )
Version Sets source control integration within BMC Remedy AR System. Setting version control options
Control (see page )
WS Registry Enables the use of the AR System Web Service Registry form by configuring a Setting a connection to the
Integration connection to a BMC Atrium Web Services Registry. Also provides a button to BMC Atrium Web Services
update the registry. Registry (see page 266)
Atrium SSO Enables the integration of the AR System server with the Atrium SSO server Setting a connection to the
Integration for the purpose of single-sign on. BMC Atrium SSO server (see
page 266)
Server Sets parameters related to server statistics. Setting server statistics options
Statistics (see page 321)
Attachment Enables you to restrict users from uploading and viewing files with certain Setting security restrictions on
Security extensions in BMC Remedy Mid Tier. file uploads (see page 317)
Call Home Allows you to share information related to product versions and server plug in Using the Call Home
configurations. Call Home also tracks the sequence of BMC Remedy AR functionality
System upgrade and the related upgrade activities.
You also need to perform the following tasks while configuring AR System servers:
Configuring firewalls with AR System servers (see page 257)

Configuring clients for AR System servers (see page 257)

Configuring a server to use plug-ins (see page 262)
Note
For information about the mid tier and BMC Remedy Mid Tier Configuration Tool, see
Accessing the Mid Tier Configuration Tool (see page 427).
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 (see page 274).
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 (see page ).
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 (see page ).
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
(see page 274).
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 (see page ). 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.

Running a stand-alone AR System server on Windows

On Windows, you can run a stand-alone BMC Remedy AR System server, which is disconnected
from the network (for example, on a laptop computer).
To run a stand-alone BMC Remedy AR System server
1. Open the C:\WINDOWS\system32\drivers\etc\hosts file (or the drive on which Windows

server is installed).
2. Enter the following alias entry:
<IPAddress> <localHostName>.<domainName> <localHostName>
Example
174.21.8.109 coyote.acme.com coyote
Many configurations of Windows require you to remove all DNS servers when running as a
stand-alone server. This avoids long pauses caused by the Windows networking software
trying to communicate with the network during BMC Remedy AR System interaction. Write
down what you removed so that you can add it back when reconnecting to the network.
3. Save the file.
4. Shut down and restart the system.
Configuring a server for alerts

To enable users to receive alerts from the server through the Alert form, you must configure your
server.
The earlier Notification Server command-line configuration options are not available in BMC
Remedy AR System 5.0 or later.
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 (see page ).
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.
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 System Administration: AR System
Configuration Generic UI form, see
Map-IP-Address in Configuration settings E-M (see page 1201).
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 page 3591). See also Setting up an authentication alias (see
page 1328).
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 (see page )). You must also start the
plug-in server (see AR System server components and external utilities (see page 1127)).
After the service is started, set up the server for external authentication as described in the
following procedure.

To configure the AR System server for external authentication
Server Information.
2. In the AR System Administration: Server Information form, click the EA tab.
3. To enable authentication using an AREA service, set the External Authentication Server
RPC Program Number to 390695.
Entering 390695 enables authentication using an AREA service. Entering no value or 0
disables authentication using an AREA service.
If you enter 0, the AR System server makes no attempt to communicate with the AREA
server.
4. Set the RPC and SYNC time-outs for External Authentication.
External Authentication Timeout (seconds)is the amount of time within which the AREA
server must respond to a call from the Plug-in server before an error is returned. The
options are
RPC — Used when making calls to the AREA server
If set to 0, the AR System server does not invoke the call to the external
authentication server. The default is 40 seconds.
Need To Sync — The interval for periodically invoking the AREA server's
AREANeedToSyncCallback() call. If set to 0, the AR System server does not invoke
the call to the external authentication server. The default is 300 seconds.
5. Select one or both of the following settings:
Authenticate Unregistered Users — Specifies that all users in the User form can
log on and be authenticated internally; users not in the form are authenticated
externally. If this option is cleared, AR System stops the validation process and
manages the user as a guest user.
Cross Ref Blank Password — Specifies that all users in the User form can log on
and be authenticated externally if the Password field in the form is left blank for that
user. If Cross Ref Blank Password is cleared, a blank Password field in the User
form is treated as no password for that user, and that user is allowed to log on.
6. Optionally, specify an authentication chaining mode.
Authentication chaining modes
Mode Description
Off Disables authentication chaining.
ARS - BMC Remedy AR System tries to authenticate the user by using the User form and then the AREA plug-
AREA in.
AREA - BMC Remedy AR System tries to authenticate the user by using the AREA plug-in and then the User
ARS form.
ARS - OS - BMC Remedy AR System tries to authenticate the user by using the User form, then Windows or UNIX
AREA authentication, and then the AREA plug-in.
ARS - BMC Remedy AR System tries to authenticate the user by using the User form, then the AREA plug-in,
AREA - OS and then Windows or UNIX authentication.

7. Specify Group Mapping options:

Ignore Excess Groups — Specifies that authentication requires that, for a given
user, at least one LDAP group must match a BMC Remedy AR System group. Non-
matching groups are ignored. If this option is cleared, authentication occurs only
when each LDAP group matches a BMC Remedy AR System group.
Group Mapping— Specifies mappings between LDAP groups and BMC Remedy AR
System groups. This eliminates the need for one-to-one matches between LDAP and
BMC Remedy AR System groups. If you do not map groups, each LDAP group must
have an exact BMC Remedy AR System group match.
Tip
For maximum benefit, use Ignore Excess Groups and Group Mapping
together.
8. Save your settings.

The settings you specify persist across server restarts.
Configuring a server to use plug-ins

You might want to use plug-ins for these purposes:
AR System database connectivity (ARDBC) — Used to create a BMC Remedy AR

System vendor form to access external data.
For information about vendor forms, see Creating vendor forms (see page 838).
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 (plug-in which is not provided by BMC), contact the plug-in service provider for
assistance.
For more information about creating ARDBC, AREA, or ARF plug-ins, see Enabling Plug-ins (see
page 719).
To configure a server to use C plug-ins
1. Modify these settings in the ar.cfg file (Windows) or ar.conf file (UNIX):
Plugin (see page )
Number of threads, for example:
Plugin-ARDBC-Threads (see page )

1.
Plugin-AREA-Threads (see page )

Plugin-Filter-API-Threads (see page )
Plugin-Log-Level (see page )
Plugin-Port (see page )
Server-Plugin-Alias (see page )
Server-Plugin-Default-Timeout (see page )
2. Modify the plug-in target password (Configuring server groups (see page )).
3. Modify the plug-in log file settings (Setting log files options (see page )).
To configure a server to use Java plug-ins

To configure a server to use Java plug-ins, see Configuring java plug-in servers (see page 357).
Related topic:
ar.cfg or ar.conf (see page 1065)
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 (see page ).
To set options for version control
Server Information.
2. Click the Version Control tab.
AR System Administration: Server Information form — Version Control tab


3. Edit the options, as needed:
Version Control tab fields

Field Name Description
Object Selecting Enforced causes the server to require object reservation. See Using object reservation (see
Reservation page 2327).
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 (see
page 264).
Object Selecting Enabled causes the server to log every change to objects. See Using the object modification
Modification log (see page 2328).
Log
Save Selecting Yes causes the server to write a definition file each time an object is created or changed.
Definition This option is available only when the object modification log is enabled.
Files
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.

1.
Group Definition set to Sub Administrator.

This group contains all users in the Sub Administrator group.
2. Grant the group Hidden permission (not sub-administrator permission) to the AR System
Version Control: Object Reservation form. A user must have access to this form to connect
to a server using BMC Remedy Developer Studio.
Setting timeout options

Use the Timeouts tab to set the timeouts for the selected server.
To set timeouts
Server Information.
2. Click the Timeouts tab.
AR System Administration: Server Information form — Timeouts tab


Timeouts tab fields
Area Field Description
name Name
Process Prevents a server from being blocked when a process requested in a Set Fields filter or
Timeout escalation action does not 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
Timeout is removed. The default is 7 seconds.
(seconds)


name Name
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
License AR System.
Timeout When a user is using a floating license, a license is reserved while the user is connected to the
(hours) server. If the user does not perform an AR System operation for the period of time specified in
this field, the license is automatically released back to the pool of available licenses. The client
tool must acquire a license for the user again when the next licensable operation occurs. The
default is 2 hours. The minimum is 1, and the maximum is 99.
Currency Client Sets the interval (in minutes) that clients (for example, the Web) use when refreshing currency
Ratio Refresh conversion ratios 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.
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. in BMC Atrium Single Sign-On online documentation.
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 (see page 3451).
For more information about the BMC Atrium Web Services Registry, see Web Services Registry
and web service registration.
Setting platform options

Use the Platform tab to view information about the platform on which the selected server is
running.
To display platform information about the selected server
Server Information.
2.
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,
Alias ACME or HelpDesk). Do not enter a fully qualified domain name. An alias makes it easier to move
workflow between computers. Entering an alias in this field does not automatically assign an alias to the
server. The network environment must reflect a change to the server name before entering the alias name
in this field. The alias name must be a valid host name on your network. If you change your server name
alias, make sure you supply the alias to the DNS or enter the alias name in your hosts file. Otherwise,
your AR System server cannot connect to the plug-in server. After you change the server environment,
users can log on to the browser by using the new server alias, just like any other server name. See your
network operating system documentation for information about creating an alias for the server.
Server Displays the current time on the server (in the local time zone).
Time
4. Click Apply.

Setting log files options

Use the Log Files tab to set one or more of the log files shown in the AR System Administration:
Server Information form--Log Files tab (see page 270) figure. BMC Remedy AR System creates
log files or forms containing information about system activity.
After being activated, logging starts immediately. You can activate logging at any time.
Warning
Do not keep logging turned on continuously. Log files can consume increasing amounts
of disk space as messages accumulate unless you limit the log file size. Monitor your disk
resources carefully while logging is active. After you activate logging for workflow objects,
logs are created for only those workflow objects that are processed after that activation.
Log files location

On the Log Files tab, the default location for log files is
(Windows) ARSystemInstallDir\Arserver\Db
(UNIX) ARSystemInstallDir/db
You can enter a different location. You can also specify the same location and file for multiple
types of logging so that all data is logged to a single file.
Log forms considerations

If you choose to log activity to a form, users can query the log form like any other BMC Remedy
AR System form.
During server installation, all the predefined log forms are imported into ARSystemInstallDir\AR
SystemserverName\ARServer\SystemForms\en. The definition file names begin with LogForm.
They are treated as system forms and are recovered from this definition file whenever the AR
System server restarts.
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 (see page ))

Log-To-Form (see Log-To-Form (see page ))
Types of logs
The following table lists the types of logs you can create.
Types of logs
Type of Description Default Default

log file name form
name
API Logs information about all API calls made by all clients. arapi.log AR
This information is logged on entry and exit of every API call. System
Log: API
Escalation Logs information about escalation activity. arescl.log AR

This information includes the escalations that executed, whether the escalation System
qualification found any matches, and any escalation actions taken. Log:
Escalation
Filter Logs information about filter activity for each operation. arfilter. AR
This information includes the filters that tried to execute and all filter actions performed. log System
Log: Filter
SQL Logs SQL commands sent to the database. arsql.log AR

This information is logged for each SQL command issued, including a time stamp and the System
user name of the user performing the operation. Log: SQL
Thread Logs information about threads being started and restarted on the server. arthread. AR
log System
Log:
Thread
User Logs information about connection activity for each user. aruser. AR
This information includes whether the user can obtain a license and when each floating log System
license is released. This enables you to keep an audit trail of user activity to help you Log: User
determine whether you need more floating licenses.
Alert Logs detailed information about user registration and about the generation and delivery of aralert. AR
alerts. log System
Log: Alert
Full Text Logs information about full text search indexer activity. arftindx. AR
Index log System
Log: Full
Text
Index
Server arsrvgrp.
Group log

Type of Description Default Default

log file name form
name
Logs information about server group activity. AR

Records information about the starting and stopping of operations, the evaluation of other System
servers, and the timing of each event. Log:
Server
Group
ARFORK ( On UNIX systems, logs all arforkd activity (a process that reduces the amount of arfork.log No form is
UNIX only memory an AR System server uses when forking new processes). created
) This file is not subject to the maximum file size specified in the Maximum Log-File Size for arforkd
field. .
DSO If you are licensed for Distributed Server Option (DSO), logs information about DSO ardist.log No form is
server activity. See BMC Remedy Distributed Server Option logging (see page 4378). created
for DSO.
Plug-In Logs the events of plug-ins that AR System uses. For more information about plug-ins, arplugin. No form is
Server see Enabling Plug-ins (see page 719). log created
for the
plug-in
server.
Archive Logs information about scheduled or on-demand archive by any user. For more ararchive. AR
Log information about archiving, see Archiving overview (see page 134). log System
Log:
Archive
For more information, see Analyzing logs (see page 4373).
To set log files or forms
Server Information.
2. Click the Log Files tab.
AR System Administration: Server Information form — Log Files tab
3.
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 Specifies the level of logging for the plug-in server. The options are
Log 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- Defines the group that can use logging options in AR System clients. Logging options are disabled for
Side users who are not members of this group. For more information about client logging, see Enabling logs
Logging (see page 4310).
Group

Maximum Defines the maximum size (in bytes) for the log file. A value of 0 (the default) specifies no limit. Except for
Log-File 0, the log file size cannot be set to less than 4096. When the log file reaches the maximum, new
Size information wraps to the top of the file, overwriting the old information. If you do not specify a maximum
(byte) 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
Backups Maximum Log-File Size value and a new log file is created. By default, the number of backup log files
allowed is 1, and the maximum number of backup log files allowed is 999.
Reload Enables JMX logging and third party loggers log level in logback_server.xml file without restarting the
Log Conf server.
File
Buffer Buffers logged lines instead of having them immediately written to disk. Selecting this option decreases the
Logged impact to AR System performance when logging is enabled. See Buffering log output (see page 4318).
Lines
Log Per Creates per-thread log files. Selecting this option decreases the impact to AR System performance when
Thread logging is enabled. See Thread log (see page 4400).
8. Click Apply.
Setting server logging options

Use the Server Events tab to select the server activities to log.
When you select specific server events, those events are logged in to the Server Events form,
thereby making server-related changes available to workflow and API programs. For information
about the Server Events form, viewing recorded server events, and using server events in
workflow, see Capturing server events for workflow or API calls (see page 1859).
To set options for server events
Server Information.
2. Click the Server Events tab.
AR System Administration: Server Information form -- Server Events tab


Server Events tab fields

Name Name
Server Specifies the name of the form populated with information about specific server events. BMC
Events Remedy AR System automatically generates this form, and the form is defined from a unique
Form combination of BMC Remedy AR System reserved fields. Only one Server Events form per server
is allowed. The default name is Server Events; you can rename the form, as needed.
Server Server Determines the objects for which changes are recorded in the Server Events form. Select the
Event Cache check box next to any of the following events to log changes to these objects:
Type Changes Active Link
Container
Escalation
Field
Filter
Import
Form
View
User Determines whether to log additions, modifications, or deletions to Users or Groups in the User or
/Group Group form, or any user or group changes using the access control utilities arcache and
Changes 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 a
Setting ARSetServerInfo call.
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
Group activities.
Actions

4. Click Apply.
Setting ports and RPC numbers

Use the Ports and Queues tab to set server ports and RPC numbers as needed to communicate
with other servers, clients, and services on the network. The Server Queue region on this tab
enables you to configure server queues and threads as appropriate for your server, taking
advantage of the multithreaded design of BMC Remedy AR System.
In this topic:
Assigning TCP port numbers to AR System servers (see page 274)

To set server ports and queues (see page 274)
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 (see page ).
Do not assign port numbers that conflict with port numbers used by other applications or programs
running on your system. If you assign conflicting port numbers, your servers might not start as
expected. To find out which port numbers are in use, enter one of the following commands at the
command-line prompt:
UNIX — rpcinfo -p
Windows — netstat -a
Client tools can use ports 0-65535.
Ports 1-1024 are reserved ports; avoid using these ports. On UNIX, port numbers within the range
1-1024 are available only for the superuser, and many of these numbers are reserved.
To set server ports and queues
Server Information.
2.
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

Field name AR System Description
Configuration
Generic UI
form option
Server TCP TCD-Specific- Defines the TCP/IP port number for the AR System server. Enables clients to have
/IP Port Port access to the server without a portmapper. When set to 0, which is the default, the
portmapper assigns the port.
Ensure that you set the same port number as the value of the server_port
parameter in the pluginsvr_config.xml file that is located in the <Install Dir>
/pluginsvr directory.
Note
If you set the Server TCP/IP Port field to a value less than 1024, older clients
cannot connect.
Distributed Obsolete. See Assigning an RPC program number to DSO (see page 538).
Server
RPC
Program
Number


Configuration
Generic UI
form option
Number of Num-selector- Defines the number of threads that can be used to monitor all live client socket
Selector threads connections for IO activity. When the thread detects any activity, it forwards the call to
Threads the appropriate queue. The default value is 1.
JMX Port Jmx-port Defines the JMX port number that enables administrators to connect to JVM by using
Java Messaging Extensions (JMX). The default port number is 61500.
Message Default- The specific port to which the JMS broker binds when sending messages to registered
Broker Port messaging- clients. The default port number is 61617.
port
Cache Peer-listener- Defines the port number where all ehcache instances from different servers
Peer port communicate with each other. The default port number is 40001.
Listener
Port
Alert The specific TCP port to which the server binds when sending alert messages to
Outbound registered clients. If multiple alert threads are started, the number represents the
Port starting port number in a consecutive range of numbers available for the alert threads. If
no port number is specified or if 0 is entered, the portmapper randomly assigns an
available port to the server.
Plugin Private-RPC- Defines a private queue for all loopback calls from the plug-in server, regardless of
Loopback Socket which plug-in application initiates the call. For more information about Plugin Loopback
RPC RPC Socket, see Private queues for loopback calls (see page 4331).
Program
Number
Register Register-With- Defines whether the AR System server and the plug-in server are registered with AR
with Portmapper System Portmapper. If the check box is
Portmapper Selected — They are registered. The server is registered if not previously
registered. AR System clients can get the port number of the AR System server
and the plug-in server from AR System Portmapper.
Cleared — They are not registered. If the server was previously registered, this
option removes the registration. AR System clients cannot get the port number of
the AR System server and the plug-in server from the portmapper.
If you are running multiple servers on a single computer, you can select the Register
with Portmapper option for one server only.
Server Private-RPC- Enables you to define server queues specific to your needs. For most types of server
Queue Socket queues, you can specify a minimum and maximum number of threads. For the
escalation queue, only the maximum threads number is used, and all threads are
started at startup time.
If you do not specify a fast or list queue or specify only one thread, three threads
are started to meet the minimum system requirements for each queue.
If the server starts more threads than specified to meet system requirements for
fast and list queues, it does not change the number specified.
For all other types, if you do not specify a number, the system defaults to one
minimum and one maximum thread per server queue.
For more information, see Defining queues and configuring threads (see page 298).
Enables you to direct all API calls from a given client type to a private queue.
Add Client RPC Mapping allows you to select the client types from the predefined list
and assign them to a private queue.


Configuration
Generic UI
form option
Client To create user defined client types, select Add Custom Client Type, which displays
Type to the Client Type Registration form and allows you to create custom client types.
RPC The settings are updated under the shared components in the Centralized
Restriction Configuration form, after you click Apply. For more information, see Configuration
Mapping settings N-R (see page 1225).
Note: You can only direct the Java API calls created using BMC Remedy AR System
9.0 Service Pack 1.
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 on the AR System
Configuration Generic UI form, and restart the server. See Plugin-Port (see page
1216).
Setting database options

Use the Database tab to view and configure information about the database that you are using.
To display and update information about the database
Server Information.
2. Click the Database tab.
AR System Administration: Server Information form — Database tab


The information displayed on this tab varies depending on the relational database you have
installed.
Database tab fields

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
Password that BMC Remedy AR System uses to access the database. The existing password is not displayed.
To change the password, enter a value in the Database Password field. The default database
password created by BMC Remedy AR System is AR#Admin#. If you changed the password and do
not remember it or if you changed it outside AR System and must reflect the change in AR System, log
on to the database as the database administrator and change it back to the default. If the encrypted
password is in the ar.confconfiguration file, delete it from that file.
Database Displays the contents of the ardb configuration file used by the advanced BMC Remedy AR System
Configuration feature that appends clauses to the SQL statements that create tables and indexes. For more
File information about the ardb file, see ardb.cfg or ardb.conf.
Database Indicates whether the database in use is case sensitive. This field is read-only.
Case
Sensitive
(Microsoft SQL Server, Sybase, and DB2 databases only) Indicates whether AR System creates the
Request ID field as a clustered index to boost performance. By default, this option is selected.

Request ID
Uses
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.
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.
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 (see page 2580).
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 name Description
Choose Allowable currency types are types that are valid entries in a currency field. These currency types are
Default visible in menus or lists in BMC Remedy Developer Studio and in client screens. From the list in the left
Allowable column, select a currency type, and click Add. Your selection is added to the table on the right, which
Types shows the three-character currency type and the default decimal precision level for that currency type. For
example, the currency type USD has a default of two decimals of precision. You can modify this precision
level by entering a new value in the Precision column. For example, to specify four decimals of precision,
enter 4. To remove a currency type, select it and click Remove.
Choose You must also specify the functional currencies stored as part of the field value. When a request is
Default submitted that includes a currency value, the server converts that value to a functional currency type and
Functional stores it. You must include at least one functional currency type. You can specify an unlimited number of
Types functional currency types; however, adding more than five currency types might have an adverse effect on
server performance. From the list in the left column, select a functional currency type, and click Add. Your
selection is added to the table on the right, which shows the three-character currency type and the default
decimal precision level for that currency type. For example, the currency type USD has a default of two
decimals of precision. You can modify this precision level by entering a new value in the Precision column.
For example, to specify four decimals of precision, enter 4. To remove a currency type, select it and click
Remove.
4. Click Apply.
Setting license options

Use the Licenses tab to display information about the type and number of BMC Remedy AR
System licenses on a server. You can also set the Submitter Mode in this tab.

To display server license information and set the submitter mode
2. Click the Licenses tab.
AR System Administration: Server Information form--Licenses tab

Licenses tab fields

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 Displays the number of forms your license allows you to create on the server. If this field reads Unlimited,
Forms you can create as many forms as you want.
Allowed
on Server

Field Description
Name
AR Displays the BMC Remedy AR System identifier code attached to the server license.
System
Server ID
Submitter Defines the conditions under which submitters can modify the requests they initially submit (that is, where
Mode their names are in the Submitter field). Select one of the following options:
Locked — Users can modify requests they submit without a write license. This does not apply to
users with a Restricted Read license who cannot modify requests under any circumstances. In the
locked submitter mode, after the entry is submitted, the value in theSubmitter field cannot be
changed.
Changeable — (Default) Users must have a write license to modify requests.
Note
Changes to the Submitter Mode settings do not take effect until the server is stopped and
restarted.
4. Click Apply.
Setting external authentication options

Use the EA (External Authentication) tab to specify the parameters necessary for BMC Remedy
AR System to authenticate users with external systems.
To set BMC Remedy AR System Administration: external authentication

parameters
2. Click the EA tab.
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
Authentication the plug-in service is 390695. Entering no value or 0 disables authentication using
Server RPC an AREA service, and the BMC Remedy AR System server accesses the
Program operating system for authentication purposes.
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
Authentication BMC Remedy AR System server when making external authentication (AREA)
Server calls before an error is returned. If this is set to 0, BMC Remedy AR System server
Timeout uses the default of 40 seconds.
(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
Unregistered User form. When a user logs in to BMC Remedy AR System, the server tries to
Users validate the user against registered users (users who are listed in the User form). If
a match is found, that user definition and the permissions specified in the matching
User record are used. If no match is found, BMC Remedy AR System continues
trying to validate the user or stops the validation process depending on whether
this option is selected. If the check box is

Selected, and External Authentication is not configured — (Default on

UNIX servers) On a UNIX server, BMC Remedy AR System searches the
/etc/passwd file or NIS password map for a match. If a match is found, the
user is considered a valid user (not a guest) of the system. The UNIX group
specification from the file or NIS is retrieved, and the user is considered a
member of the BMC Remedy AR System group whose Group ID matches
the UNIX group. On a Windows server, BMC Remedy AR System
authenticates to the default domain. The optional authentication string that
the user enters when logging in is used as the Windows domain name for
authentication purposes. On Windows servers, the user is considered a
member of the group whose Group ID is 0.
Selected, and External Authentication is configured — BMC Remedy
AR System sends a request to the external authentication server to
authenticate the user. If a match is found, the user is considered a valid
user (not a guest user) of the system. SeeConfiguring a server to use plug-
ins. The authentication string entered by the user when logging in is passed
to the external authenticator for its use.
Cleared — (Default on Windows servers) BMC Remedy AR System stops
the validation process and manages the user as a guest user if Allow Guest
Users is enabled.
For information about configuring external authentication, see To set server ports
and queues.
Cross Ref Defines how BMC Remedy AR System authenticates a user whose User form
Blank record has no password. When a user logs in, BMC Remedy AR System searches
Password its own database for that user. If the user has a password, the system uses it. If
the Password field is empty and this option is
Selected — BMC Remedy AR System tries to validate the password
against one of the following items:
An external authenticator if one is configured
The password in the Windows server domain
The UNIX server's /etc/passwd file
Cleared — (Default) BMC Remedy AR System concludes that an empty
password field means that the user has no password.
In the Login window, users see an Authentication field. If your AR System server
is running on Windows, the contents of this field are used as a domain name when
the server authenticates the user with the operating system. If the server is instead
configured to use an external authenticator, the contents of this field are passed to
the authenticator. See Setting up an authentication alias. If you enable the Cross-
Reference Blank Password option, make sure that it does not conflict with the
User Password Management feature. If you enforce a password policy, BMC
Remedy AR System periodically forces users to set a password that cannot be
blank. If a user's password is authenticated outside of BMC Remedy AR System
and that user sets a non-blank password, BMC Remedy AR System performs the
authentication. This is not an issue if enforcement of a password policy is not
enforced. If a policy is enforced, you must disable the policy for users whose
passwords should be blank. For information about enforcing password policies, see
Enforcing a password policy introduction. To disable the policy for users whose
passwords should be blank, see Disabling password management for individual
users.
Authentication Specifies the order in which BMC Remedy AR System tries to authenticate users
Chaining Mode when they log on:
Default — Disables authentication chaining.
ARS - AREA — 1) the User form; 2) the AREA plug-in.
AREA - ARS — 1) the AREA plug-in; 2) the User form.

ARS - OS - AREA — 1) the User form; 2) Windows or UNIX authentication; 3) the

AREA plug-in.
ARS - AREA - OS — 1) the User form; 2) the AREA plug-in; 3) Windows or UNIX
authentication.
Group LDAP Area The name of the LDAP group to map to the BMC Remedy AR System group in the
Mapping name same row of the Group Mapping table.
AR Group The name of the BMC Remedy AR System group to map to the LDAP group in the
Name same row of the Group Mapping table.
Ignore Excess Enables BMC Remedy AR System to authenticate a user when any single LDAP
Groups group to which the user belongs matches a BMC Remedy AR System group.
Setting performance and security options

Use the Advanced tab to create settings for performance and security:
2. Click the Advanced tab.
AR System Administration: Server Information form — Advanced tab
3. Edit the options listed in the following table, as needed, and click Apply.
Advanced tab fields

Area name Field name Description
Default Web Specifies the base URL for the mid tier and is used by clients such as Flashboards.
Path The URL looks like this:
http://<hostName>/<contextPath>
hostName is the name of the server (for example, eng.remedy.com).

contextPath is the URL context path of the AR System application registered

with the servlet engine. This is set up during installation. The default value is
arsys. If your company has multiple domains, use a fully qualified path name.
Maximum For forms that contain hierarchical data, such as manager and employee relationships,
Depth for specifies the maximum number of levels in the hierarchy that a recursive query
Hierarchical retrieves. By default, the maximum is 25. Enter any integer greater than 0. See
Query ARGetListEntryWithMultiSchemaFields (see page 3848).
Maximum Specifies the maximum number of temporary tables that can exist on an AR System
Vendor server for a single vendor form. The ARGetListEntryWithMultiSchemaFields
Temp function stores data from vendor data sources in these tables. By default, only one
Tables 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 (see page 3848).
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
Line Length single line of the message is over this length, a return is automatically inserted. Limits
in Email the line length of email messages passed 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
Notification Default Web Path is used. (The Email Notifications Web Path field is available because
Web Path the Default Web Path is specified for other applications like Flashboards, and it might
be different from the mid tier web path for opening requests in a notification.) If your
company has multiple domains, use a fully qualified path name.
Security Active Link Specifies the only directory that the Run Process active link action can run from, for
Run example, C:\arsys. If no directory is specified, active link processes can run from any
Process directory.
Directory
Active Link Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no
Run path is specified, administrators can specify any shell.
Process
Shell (UNIX
servers
only)
Allow Enables the administrator to use the arcache and arreload utilities. See arcache.exe
arcache or arcache (see page 1136) and arreload.exe or arreload (see page 1139). The option is
and arreload selected by default.
Transaction Maximum Specifies the maximum number of client managed transactions (CMT) which are
Control Connections allowed on the system. Valid values are 0 to 100. When set to 0, CMT is disabled on
that system. The default is 10.
Transaction Specifies the maximum allowed time interval (in seconds) between client managed
Timeout transaction API calls. When a client managed transaction starts, if the consecutive API
(seconds) call is not made within the specified time interval by the client, then the server rolls
back the transaction and the transaction handle becomes invalid. Valid values are 0 to
600. The default is 60.

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
Messages entries in localized forms, or using BMC Remedy AR System Message Catalog
to load the message. Clients are enabled to display localized messages, but
clients still have local catalogs, such as the user.dll. You must select the
Localize Server check box to see localized error messages.
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 (see
page 440).
Catalog Displays the name of the form the server uses to resolve error messages when
Form Name Localize Server is selected. For more information about the BMC Remedy AR System
Message Catalog form, see Localizing BMC Remedy AR System applications (see
page 3181).
Filters Maximum Specifies the number of filters that can be performed in an operation. The default and
Filters for recommended number is 10000. Increase this number at your own risk only if you
an reach a limit in your system and you have verified that your workflow is valid.
Operation
Maximum Specifies the maximum number of nested filters and filter guides that execute to
Stack of prevent recursive actions on the server. The default and recommended number is 25.
Filters Increase this number at your own risk only if you reach a limit in your system and you
have verified that your workflow is valid.
Server Group Server If the server belongs to a server group, specifies the name of the group. All servers in
Group the server group share this setting.
Names
Check Specifies how often the server communicates with other servers in the group. Each
Interval server can register its own status, determine whether any server is delinquent,
establish the parameters needed for sending signals, and determine operational
responsibilities. Values are
Default — 60 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
Option server might or might not be used depending on whether the Centralized
Preference forms are defined.
Use This Server — Users must use a preference server, and this server is an
available preference server.
Use Other Server — Users must use a preference server, and this server is not
available as a preference server.
See Establishing a mandatory preference server (see page 1346).
Preload Preload If the number of preload threads is not zero, specifies whether the threads are used
Tables Tables At only at server startup or for all cache reloads from the database. See Setting the
Configuration Init Only Preload Tables Configuration option (see page 369). Values are

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 (see page ).
Number of Specifies the number of preload threads used when information is loaded from the
Preload database into the server cache. The maximum value is 30 or twice the number of
Threads preload segments, whichever is lower. The server might reduce the number of threads
at runtime if it determines that threads would be started with no work to do. If this field
is set to 0, the Preload Tables Configuration option is off. For information about the
corresponding configuration file setting, see Num-Preload-Threads (see page ).
Number of Specifies the total number of preload segments handled by the preload threads. Vary
Preload this setting to balance the load between preload threads and to optimize cache load
Segments time. A good initial setting for this option is 1/3 the number of schemas (forms) in the
AR System server. See Determining the optimum preload settings (see page ). For
information about the corresponding configuration file setting, see Num-Preload-
Schema-Segments (see page ).
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 (see page 462) in the table
below.
Set the RPC program number and port information for plug-in and DSO servers.
Configure timeout settings for the plug-in servers.
To set connection settings
2. Click the Connection Settings tab.
AR System Administration: Server Information form — Connection Settings tab


3. Edit the options on the tab as needed:
Connection Settings tab fields

Tab Field name Description
name
Application Specifies the password that the Email Engine and Flashboards server use to access the
Service AR System server. Asterisks in the field indicate that a password is defined. If you change
Password this password on the AR System server, you must also change it for the Email Engine and
Flashboards server if they are installed. To change the Application Service Password for
the Email Engine, update 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
Administrator change this password on the AR System server, you must also change it in the Mid Tier
Password Configuration Tool, which updates the 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
Server Password this server's plug-in server. If this option is specified, the plug-in server accepts
connections only from AR System servers configured to use the same password. If you
change this password, you must also change the appropriate plug-in server target
password on any AR System servers that connect to this plug-in server. See Setting
server passwords, RPC options, and plug-in timeouts. If this option is not specified, the
plug-in server accepts connections from AR System servers not configured to use a plug-
in server target password.
Plugin Specifies the number of seconds in which the plug-in server must respond to the AR
Default System server before an 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.

Tab Field name Description

name
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
Server Password change DSO Server password, you must also change the target password for any DSO
servers that connect to this AR System server. See Configuring BMC Remedy
Distributed Server Option .
DSO Local Specifies a dedicated (private) RPC program number that a DSO server uses for all
RPC Program communication with the AR System server. If you leave this field blank, the fast and list
Number queues process all distributed operations.
Target Specifies RPC program numbers, TCP/IP ports, and DSO passwords that a DSO server
connection uses when accessing remote AR System servers. See Configuring BMC Remedy
settings Distributed Server Option .
tables
Remote Local Specifies the password that another AR System server uses to access this server through
Workflow Password workflow. If you change this password, you must also change the appropriate remote
workflow target password on any server containing workflow that connects to this server.
Server Name Specifies the name of the remote server.

Note: In this tab's table, you enter target connection settings. The AR System server uses
these settings to connect to other AR System servers when required by workflow.
Password Specifies a password to use when this server accesses the specified remote server
through workflow. This occurs when an active link contains an SQL or Process command
against the remote server and is activated by a non administrator user. If the remote
server specifies a workflow password, you must register that server and password, or you
cannot access that server through workflow. The edit masked option is not supported in
tables on forms. Therefore, when you type a new password in the Password column, it
is visible. Saved passwords are masked.
4. Click Apply.
5. Restart the AR System server for the Connection Settings to take effect.
Note
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 (see page 291).

Setting administrative options

Use the Configuration tab to set administrative options.
To set configuration options
2. Click the Configuration tab.
AR System Administration: Server Information form — Configuration tab
Edit the options, as needed:
Configuration tab fields

Users Specifies whether users are prompted for their log on credentials.
Prompted For By Preference --- The prompt appears by preference.
Login 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
Returned by entries to 50 would return a maximum of 50 entries, even if more entries satisfied the search
GetList qualification. BMC Remedy AR System warns users that the search matched more entries than the
administrator allows to be retrieved. If users specify a maximum in their preferences, the lesser value
is used. A value of 0 (default) specifies no limit.

Server Table For server-side table fields, determines the number of entries (or size of the chunk) that the server
Field Chunk retrieves at one time from the database and stores in-memory to process during filter or filter guide
Size 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 Displays the language and character set of the computer on which the server is running.
Language
User Email Identifies the sender of email notifications. The default sender for email notifications is ARSystem. To
Notifies From specify another user name, enter that name in this field. The name must match the name you use in
the BMC Remedy AR System Email Configuration Form for notifications. For more information about
configuring a mailbox for notifications, see Sending notifications (see page 1467).
Minimum API Specifies the oldest version of the C and Java APIs with which the server communicates. The
Version corresponding API and 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 (see page ).
Default Home Specifies the path to a home page form to be used system-wide as the default home page for this
Form server when a user logs in. This default Home form is only used if one of the following statements is
true:
This server is designated as the server for the home page in the BMC Remedy AR System
User Preference form.
This server is designated as the home page server on the General Settings page in BMC
Remedy Mid Tier Configuration Tool. See Homepage Server (see page ).
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 Specifies the maximum number of consecutive bad password attempts a user is allowed. If you enter
of Password 3, the user has 3 chances to log on. If all 3 attempts have bad passwords, the user account is marked
Attempts INVALID. Values for this field are 0 (turns features off) and all positive integers. This option can also
be set with the AR System Configuration Generic UI form (see page 1235).
This parameter can be used in conjunction with Display-General-Auth-Message. See Configuration
settings C-D (see page 1168). See also the description for error 624 (see page 4500).
Next Request Specifies whether to allocate Next-IDs in blocks rather than one at a time. Allocating in blocks
ID Block Size increases performance during a create operation. To allocate in blocks, enter a positive number
greater than 1 (up to 1000). The default value is 1 (Next-IDs are not allocated in blocks). If 0 or a
negative number is used, the server uses the default value of 1. You do not need to restart the server

for the change to take effect. The option is started immediately. Warning: The use of this configuration
setting might result in unpredictably large Next-ID sequence gaps. The likelihood of this occurring
increases with the use of multiple servers that share a database. The BMC Remedy AR System server
does not malfunction because of this gap and should not be considered a defect.
Allow Guest Specifies whether BMC Remedy AR System permits access to guest users, who are not registered
Users 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 (see page 1287).
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 (see page ).
Give Guest Defines whether guest users receive a restricted read license when they log on to BMC Remedy AR
Users System. If this option is not selected, guest users receive a read license.
Restricted
Read
Allow Defines whether the server accepts unqualified searches (searches for which no search criteria are
Unqualified specified). If the check box is
Searches 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- Enables only administrators and sub-administrators to access BMC Remedy AR System. Users who
Only Mode are not administrators or sub-administrators cannot perform any BMC Remedy AR System operations.
This is useful during system maintenance. By default, this option is not selected. Only administrators
(not sub-administrators) can set the Administrator-Only Mode. After an administrator sets this option,
sub-administrators can access only forms for which they have permission.
Disable Disables the archive operations on the server. You can disable one server operating with one
Archive 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 (see
page 1895). 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 (see page 342).
Development The check box is not selected by default.

Cache Mode Note: You should not change the default value.
Server Group Indicates whether the server is a member of a server group. By default, this option is not selected.
Member
Disable Disables certain operations performed only by administrators and sub-administrators, which enable
Admin you to control changes to the database by disabling administrator (Developer Studio) operations. You
Operations 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. SeeConfiguring server groups.
Disable Enables you to stop escalations running on the server. You can disable one server operating with one
Escalations 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 (see page 342).
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 Indicates whether the server needs to check its list of registered alert clients to determine if they are
Users 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 Enables multiple roles, groups, and user names to be stored in the row-level security Assignee Group
Multiple field (ID 112) and in dynamic group fields (ID 60000-60999). This enables multiple users, or users
Assign from multiple groups, to access the same entry (as in the sample qualification, 'Assignee Group' = ";
Groups 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
Unicode clients. This check box is visible only for AR System 7.0.00 servers or later. If the server uses a non-
Clients Unicode database, the check box is disabled.
Record Determines whether the AR System server records the relationships between workflow objects. If the
Object 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.
When you select the check box, it records the relationships of all server objects before it
accepts connections from clients. Therefore, the first time you set the value to T, you
cannot connect to the server by using any client temporarily. The more the number
of objects defined on the server, the more time it takes to connect to the server. With a
large number of objects, such as with an ITSM application installed, and depending on
the performance of the database, this could take up to an hour. When you can reconnect
to the server, the recording of object relationship data is complete.

When you clear the check box, 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 (see
page 3278). For more information about Search and Show Relationships, see Relationships tab (see
page 2254). 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 Specifies the maximum size of the attachment in bytes. The default is 0, which allows users to attach
Size files of any size.
Use Prompt Specifies whether system messages appear in the prompt bar or a pop-up box. The options are:
Bar 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 The number of seconds that the recache is delayed.

Delay
Required Specifies the character to add to the label of a field whose entry mode is Required.
Field 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 (see page 2646).
Display This option can be set to restrict the number of form display properties the server loads into memory at
Property startup. The result of a restricted option (Cache Only Server Display Properties) is less memory use
Caching 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 (see page 2394).
License Determines whether information is recorded in the AR System Current License Usage and AR System
Tracking Historical License Usage forms. By default, this option is not selected (information is not recorded in
the forms). For information about tracking license usage, see Displaying and Tracking server group
license usage (see page 247).
Causes the system to disable ARSignals. By default, this check box is not selected.

Disable
ARSignals
Disable Audit Causes the system to record all fields when auditing a record. By default, this check box is not
Only selected, indicating that only those fields whose values have changed during a transaction are audited.
Changed
Fields
Monitoring service operations

You can track the number of service operations performed by the AR System server. You can
track:
The number of emails sent from AR System server in an hour

The number of emails received by AR System server in an hour
Note
Using the 2014.01 version, you can monitor only email services.
The following topics are provided:
Enabling service operations (see page 296)

Adding service operations that you want to track (see page 297)
Viewing the service operations details (see page 298)
Related topic (see page 298)
Enabling service operations

As a BMC Remedy administrator, you can track the incoming and outgoing emails by selecting a
check box in the AR System Server Information — Advanced tab. If you have not selected this
option, you will not be able to track the service operations.
To enable tracking of service operations
Server Information.
2. In the AR System Administration: Server Information form, click the Advanced tab.
3. In the Enable Service Recording drop-down list, indicate whether you want to enable the
system for tracking service operations. By default, tracking is disabled.

Adding service operations that you want to track

You can configure the service operations that you want to track using the AR System Service
Statistics Configuration form. This form allows you to enable service operations for particular
service types. Using the 2014.01 version, you can monitor only email services.
Recommendation
You must follow the steps displayed in this section to configure the tracking of service
operations. If you have not set the following parameters for a service operation, it will not
be tracked.
To add service operations
1. Open the AR System Service Statistics Configuration form by typing the URL in a
browser in this format: http://<midtier>:<port>/arsys/forms/<server>
/AR+System+Service+Statistics+Configuration.
The AR System Service Statistics Configuration form opens.

(Click to expand the image.)
2. Enter the values for the following fields:

Service Type –- Indicates the service type, for example, com.bmc.arsys.email.
Select the service type from the available service types.
Service Operation — Indicates the service operation, for example, incoming,
outgoing. Select the service operation from the available service operations.
Monitoring Status — Indicates the status of a service operation for tracking. Select
ON or OFF from the list to enable or disable tracking.

Viewing the service operations details

The information about the tracked emails is recorded in the AR System Service Statistics form.
To view the details, open the AR System Service Statistics form by typing the URL in a browser
in this format: http://<midtier>:<port>/arsys/forms/<server>/AR+System+Service+Statistics.
The AR System Service Statistics form displays the following fields:
AR System Service Statistics form fields
Field name Description
Service type Indicates the service type

For example, com.bmc.arsys.email.
Service Indicates the type of service operation

operation
For example, incoming, outgoing
Count Indicates the total number of service operations. For example, incoming and outgoing emails.
Start Indicates the time when the service tracking started. Start time is specified in hours. The tracking time frame
Timestamp is 1 hour.
End Timestamp Indicates the end time of service tracking

For example, if the start time is 5/25/2013 2:00:00 AM , the end time will be 5/25/2013 3:00:00 AM.
Server Indicates the IP address of the computer where the AR System server is running
Related topic
Setting performance and security options (see page 285)
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
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 Number column, and enter the appropriate number for the queue that
you want to add:

4.
Type RPC Prog Number Default Default

Min Max
Threads Threads
Alert 390601 1 1
Full Text 390602 2 2

Indexer
Escalation 390603 1 1
Fast 390620 3 6
List 390635 3 6
Private An RPC program number in the following ranges: 2 2

390621-390634
390636-390669
390680-390694
Note: If you do not configure a private queue, its operations are executed by
the default dedicated queue (Fast, List or Admin).
Note
To enable the debug queue, the Min Threads and Max Threads count
must be 1.
If you do not want to enable the debug queue for the list and fast threads,
the minimum number of threads must be 2.
Even if you delete the escalation queue, the AR System server starts the
thread in the background.
5. In the Min Threads field, enter the minimum number of threads that you want started at
startup.
The default is 1.
6. In the Max Threads field, enter the maximum number of threads that your system is allowed
to start.
The default is 1. When all the existing worker threads are in use, the system starts
additional threads as needed until the maximum number is reached. These additional
threads remain active until the server is rebooted.
For the escalation queue, the maximum number of threads are started when the server
starts up.
7. Select the Yes check box to create a debug queue to work with the workflow debugger.
See Configuring the server for debugging workflow (see page 3269).
When you return to the form, the new queues are listed.
Note

8.
If you have removed a queue or decreased the maximum number of threads for a
queue, restart the server for the changes to take effect.
Changing a server name when using a duplicated or migrated

environment
BMC Remedy AR System Server changing server name checklist
Update the Customization Comments column and check the tasks as you complete them.
Download checklist
This section describes the configuration procedures required to change the server name of a BMC
Remedy Action Request System (BMC Remedy AR System) server. The steps involve updating
one or more of the following items:
(Windows only) Registry information using regedit

Configuration files using a text editor
Form data using a BMC Remedy AR System client, such as a browser
Server-Name is the alias name by which an AR System server recognizes itself. You might need to
change a Server-Name alias because:
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
case restoring the database from the production server. The database might contain references to the production server, which
1 might not be applicable to the staging environment. In this case, you need to change only the form data.
Use You are setting up a staging server (as part of the upgrade process) by restoring the database first and then installing the
case new BMC Remedy AR System environment (this is called an accelerated installation). In this case, you need to change
2 only the form data.
Use The Server name is changing due to a policy or host name change. In this case, you must change the Registry (on
case Windows), the 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
case Registry (on Windows), 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 the upgrade in BMC Remedy ITSM Deployment
documentation.
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 (see page 301)

ar.cfg (ar.conf) (see page 301)
armonitor.cfg (see page 302)
pluginsvr_config.xml (see page 302)
server.conf (see page 302)
Making service registration changes on Windows (see page 302)
Updating UNIX environments (see page 303)
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.
3.
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.)
Updating the server name in application forms to rename the server

The following procedure describes how to update the server name in the various application forms
listed in the following table.
1. In a browser, open the form in Search mode.

2. In the field listed in the following table, enter the old server name, and click Search.
Do not enter any information in the other fields before performing the search.
3. In the field listed in the following table for each record, replace the old server name with the
new server name, and save the record.
Product Form Field name Field ID
BMC AR System Searches Preference Server 51004

Remedy AR
System
AR System User Preference Server Login List 20100

Product Form Field name Field ID
BMC
Remedy AR
System
BMC Report Server 2000018

Remedy 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 AR Login Info Server 301286600

Remedy IT
Service
Management
BMC AST:ComplianceARBased_Advanced AR Server Name 303000501

Remedy IT
Service
Management
BMC SYS:Escalation Record Server 230000011

Remedy IT
Service
Management
BMC SYS:Attachments (If the out-of-box data for Survey is modified URL 1000002261
Remedy IT by replacing the <arserver> or <midtierserver> placeholders with
Service the host names, only then change these values to the correct
Management 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).
This topic provides the following information:
Limitations of using the Maintenance Tool to replace server references (see page 305)
Before running the Maintenance Tool utility (see page 306)
To rename the server name references in the database form by using the Maintenance Tool
(see page 306)
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 in BMC Remedy ITSM Deployment documentation. (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.
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. In the EmailDaemon.properties email server configuration file, replace oldServerName

with newServerName. For example:
com.bmc.arsys.emaildaemon.servers=<oldServerName>.labs.bmc.com
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.TCP=0
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.RPC=0
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Language=en_US
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.
Password=M7D17cnnrgyyQnLF1RgTctJ6w6xtv+Tzdb9Ag3SdrbBgfgQ6SV54mic6HG/
xtJM1Fyu8FABW/C4h0zOv/rObN3CLl/Y9Y12VVw0ngJe5r+VCyqE5vo95FA==
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Interval=30
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Authentication=
2. In a browser, open the AR System Email Mailbox Configuration form. (This form appears
only if Email Engine is installed.) Go to http://<newServerName>:<port>/arsys/forms
/<newServerName>/AR+System+Email+Mailbox+Configuration/Default+Admin+View/.
3. In the Email Server Name/IP field, enter the new email server's name. (Make this change
only if the actual Email Post Office server has changed.)
Configuring the BMC Remedy Flashboards server to rename the server

To update the server name in the Flashboards server, update the ARServerName property with
the new server name in the server.conf file in the Flashboards folder.
Configuring the BMC Remedy AR System Web Services registry to rename the
server
The following procedure describes how to update the server name in the BMC Remedy AR System
Web Services registry.
1.
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.
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. 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.
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. 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. Update the UDM:Config (see page 1946) 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 (see page 1957) 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:ExecutionInstance (see page 1949)form.
a. In a browser, open the UDM:ExecutionInstance form.
b. Delete all the existing entries.
4.
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 (see page
1956) 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.
7. Update the new server name in Job scheduler.

a. Open the Atrium Integrator console.
b. Select the desired job.
c. Open the Manage Job Schedule dialog box.
d. In the Carte Server drop-down list, select the new server name.
e. Click Save.
You will have to repeat the steps for each job.
Setting security restrictions on file uploads

You can restrict BMC Remedy AR System users from uploading and viewing files with certain
extensions in BMC Remedy Mid Tier. This feature helps prevent users from uploading malicious
attachments and viewing them.
Restricting attachments (see page 317)

Disabling views (see page 320)
Restricting attachments
Use the Attachment Security tab in the AR System Administration: Server Information form in the
BMC Remedy AR System Administration Console. You must be logged on as an administrator to
perform this procedure.
To restrict attachments
Server Information.
2. Click the Attachment Security tab as shown in the following figure:
3.
3. Enter the attachment options that you need, and click Apply.
The following table describes the available options:
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
exception Module(3450298).
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
plugin name
performing functions like verifying the attachment containing malicious content, verifying whether the attachment
is a virus, verifying whether the user has changed the extension for uploading the attachment, and so on.
Example: EXAMPLE.ARF.SIMPLE (name of the custom plug-in that you developed)
If you are using a C plug-in, add the .dll/.so path in the ar.cfg or 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 Include all Allow attachment Allow Allow Disallow Disallow

criteria attachments with the following attachment attachments with attachments with attachments with
extensions with the the following the following the following
following extensions extensions extensions
extensions
Comma doc xls jpg doc xls jpg gif doc xls jpg gif doc xls jpg gif exe dll db exe dll db
separated gif
list of limit
extensions
Attachment - Data Visualization - - - -

exception Module(41006),
list Report (2000012)
example.doc, example.exe, example.doc, example.exe,

example.jpg example.db example.txt example.dll

Parameter Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 5 Scenario 6
Attached example. example.jar (JAR

File dll, File field on Data
examples example. Visualization
gif Module form)
Status File is File is attached. File is File is not File is attached. File is not
attached. The JAR File field attached. Its attached. Its Its extension is attached. Its
All ID is added to the extension is on extension is not not on the list of extension is on
attachment attachment the list of on the list of disallowed the list of
options are exception list. permitted permitted extensions. disallowed
permitted. extensions. 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.
Server Information.
2. Click the Attachment Security tab, shown in the following figure
3. Enter the display options that you need, and click Apply.
The following table describes the available options:
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 Lists the attachment extensions that you want to allow or not, based on Display criteria.
list 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.
Setting server statistics options

The AR System server enables you to gather performance statistics on the server. You can also
gather statistics about the longest running SQL and API calls.
The AR System server adds exception logging, where API and SQL performance exceptions are
recorded in a new log file, arexception.log.
Finding out which calls are causing delays can help you troubleshoot performance issues.
For details about the performance exception logging feature, see Exception Logging (see page 324
).

To gather statistics about the longest running SQLs and APIs
1. On the AR System Administration: Server Information form, click the Server Statistics tab.
2. In the API/SQL Performance Tracking section, complete the following fields:
Field Description
Enable When selected, displays API and SQL events in the console when an automatic save is triggered (by the time
Console specified in the Auto Save and Purge Interval (min) field) and when you click one of the Save buttons:
Display
Save Completed API
Save Completed SQL
Save Pending API
Save Pending SQL
This is a debugging aid that is available if you are running the server from a command window. (This option is
not available when you are running the server on Windows as a service because there is no console.)
The default is off (not selected).
Enable When selected, enables exception logging, where all API and SQL calls that exceed the value specified in the
Exception Minimum Elapsed Time (mSec) field are immediately written to the arexception.log file.
Logging
Number of Defines the maximum number of completed longest operations that can be saved in memory. The number
Saved applies to both API and 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 Defines the interval (in minutes) for when the longest operations saved in memory are flushed to the
and Purge corresponding forms in the database and then purged.
Interval
The default is 0 (no interval); no automatic save and purge are performed. If you change the interval, the new
(min)
interval is used if it is less than the time remaining for the old interval. Otherwise, the new interval is used after the
current interval expires.
Sets the minimum duration of the longest API and SQL events saved in the memory buffer in milliseconds. Any
event shorter than this value is discarded.

Field Description
Minimum If an event is at the minimum or a greater number of milliseconds, it qualifies to be saved. Consequently, if the
Elapsed event is not one of the longest operations in the list, it is not saved. (The maximum is defined by the Number of
Time (mSec) Saved Operations field.)
The default is 5,000 milliseconds. If you enter 0, all events (up to the limit set in the Number of Saved
Operations field) are saved.
To manually flush the statistics and view the results
1. On the AR System Administration: Server Information form, click the Server Statistics tab.
2. Click the appropriate button for the type of statistics you want to gather:
Save Completed API
Save Completed SQL
Save Pending API
Save Pending SQL
The Save Pending API and Save Pending SQL buttons record the API calls and SQL
commands that are currently in process. In-process events are not subject to the Minimum
Elapsed Time setting.
The Save Completed API and Save Completed SQL buttons record the longest API and
SQL operations that are currently saved in memory. After flushing to the corresponding
forms in the database, the currently saved operations are cleared from memory.
3. To view the results:
a. Open the appropriate form by entering one of the following URLs:
http://<midTierServer>/arsys/forms/<ARSystemServer>/Server Statistics:
Longest APIs
http://<midTierServer>/arsys/forms/<ARSystemServer>/ Server
Statistics: Longest SQLs
b. Enter search criteria, and click Search.
Information gathered in the statistics forms

The Server Statistics: Longest SQLs form or the Server Statistics: Longest APIs form contains the
following information:
Field Contents
API name Text name of the API associated with the event (or INTERNAL)
User User name associated with the event (or SYSTEM)
Thread ID ID of the thread associated with the event
Result Error code that resulted from the event. If there is no error, 0 is the error code.
Code
Start Time Time that the event started
Server Name of the server where the event occurred. All servers in a server group share the same form.
Name

Field Contents
Parameters (API only) Additional details about the API call (for example, the form name on entry-related calls)
SQL (SQL only) First 1,000 characters of the SQL command issued to the database
Command
Extended If the API parameters or SQL command exceed 1,000 characters, the entire string is contained in this field.
Data
Elapsed Time (in milliseconds) required to complete the event. For SQL events, this time represents the statement
Time execution only. It does not include any subsequent record retrieval time.
(mSec)
Client Type Text name of the type of client used to send the API (or Unidentified Client)
RPC ID Unique ID of the event RPC, or 0 (if generated internally)
Create Origin of the event recording:

Mode
Auto — Longest API or SQL event that was recorded at an Auto Save and Purge Interval (the option
selected on the Server Statistics tab on the AR System Administration: Server Information form).
Demand — Longest API or SQL event that was recorded from an on-demand request
In Process — Incomplete API or SQL event that was recorded from an on-demand request
Queue (API only) Time (in milliseconds) in the thread queue before processing started
Delay
(mSec)
Data (SQL only) Reserved for future use

Retrieval
(mSec)
Create Date and time the entry was added to the form (not the event time)
Date
Exception Logging
The BMC Remedy AR System server adds exception logging to the API and SQL server statistics
feature. This feature provides additional options for managing API and SQL performance
statistics. The key additions are:
A new log file, arexception.log, is the repository for all exception-logging activity. The
arexception.log file is managed like the arerror.log file.
API calls that reach the server and are not completed before the client times out are logged
to arexception.log. A client timeout server event is also available that allows client timeouts
to be detected through server workflow.
API and SQL calls that exceed the defined minimum time threshold are logged immediately
to arexception.log if the exception-logging option is enabled.
You enable exception logging for the performance statistics feature on the Server Statistics tab of
the Administration Server form by selecting Enable Exception Logging in the API/SQL
Performance Tracking form.

For more information about the API/SQL Performance Tracking form, see Setting server statistics
options.
Server Statistics tab
This document covers the following topics:
arexception.log contents (see page 325)

Logging Messages (see page 326)
Logging long-running API and SQL to the exception log (see page 326)
Client timeout logging (see page 326)
1. Pre-execution check (see page 327)
2. Post-execution check (see page 327)
Long-running API and SQL calls (see page 327)
Standalone SQL (see page 328)
Standalone SQL that produced an error (see page 328)
SQL call within an API call (see page 328)
API call (see page 329)
Server Event support for client timeouts (see page 329)
Server event workflow (see page 330)
arexception.log contents
Like the arerror.log file, the arexception.log file is created automatically with no options for its
name or location. Log lines are always appended to arexception.log, and the file does not have
an artificial size limit. The AR Server version string is written to arexception.log every time the
server starts up.
The contents of a log segment consist of the following components:
Message that describes why logging is occurring

Timing statement to quantify why this operation is being logged
Log lines (in the same format as if they had been logged to the API or SQL log)

Status messages, should any notes, warnings, or errors occur during execution
The following figure shows an example of the arexception.log file:
Logging Messages
The format of the exception log is similar to the arerror.log file in that each entry starts with a
message, followed by supporting information. A message is tagged as an ARNOTE. The following
messages are used in exception logging:
SQL operation elapsed time has exceeded the configured threshold

(ARNOTE 595)
API operation elapsed time has exceeded the configured threshold
(ARNOTE 596)
API operation did not complete prior to the client timeout (ARNOTE
597)
API and SQL operation did not complete prior to the client timeout
(ARNOTE 598)
Logging long-running API and SQL to the exception log

With the existing performance statistics feature, API and SQL calls that exceed the threshold value
and are within the top 20 (or the value specified in the Number of Operations field) were saved in
the AR Server's memory. That collected data can be written to a form on a scheduled basis or on
demand. When exception logging is enabled, all long-running API and SQL calls are immediately
written to the arexception.log file. Writing to the exception log is independent of saving the top 20
collected calls: both methods may be used, one may be used, or neither may be used.
The threshold value for long-running API and SQL calls is specified in the Minimum Elapsed Time
field of the API/SQL Performance Tracking form. The threshold value is shared with the
performance statistics feature, with a default value of 5,000 ms (5 seconds).
Client timeout logging

Logging client timeouts for calls that reach the server is not optional: each time the AR Server
detects this condition, it is written to the exception log based on pre-execution or post-execution
checks:

1. Pre-execution check
This occurs when an API has just started being processed by the thread assigned to the call, and
the call is not one that performs updates. This check ensures that the call has not already spent all
of its time in the Dispatcher queue and that it does not start performing any work when the client is
no longer waiting. This type of call is logged as a failure, because the server records an error in the
status. For example:
2. Post-execution check
This occurs when the call is completed and the API performance statistics have been gathered.
This type of call is logged as a success or failure depending on what occurs when the call runs.
There are two variations of this occurrence:
An API call with no SQL identified as the root cause of the timeout -- If multiple SQL
statements within the API exceed the client timeout by themselves, only the first and most
important SQL statement is included.
An API call with an SQL statement that exceeds the client timeout value - -If multiple SQL
statements within an API each contribute to the excessive overall time, but none in
particular exceed the client timeout, no SQL statement is included. Diagnosing this case still
requires full API/SQL/filter logging.
The following figures show examples of the two cases. The first shows an API call with no SQL,
and the second shows an API call with an SQL call that exceeds the client timeout:
Long-running API and SQL calls

Logging long-running API and SQL calls to the exception log depends on enabling exception
logging in the API/SQL Performance Tracking form. After they are enabled, all calls that exceed
the minimum elapsed time value are immediately recorded in the exception log. Gathering

performance statistics occurs regardless of whether exception logging is enabled. Saving the top
20 long-running API or SQL calls in memory does not influence logging behavior. Qualifying items
are not saved in the Top 20 list if the list already has 20 items of greater elapsed time, but all long-
running API and SQL calls are logged. The following logging scenarios are possible:
Standalone SQL
The following example shows a typical logging sequence for an SQL call with no associated API
call:
Standalone SQL that produced an error

The following example shows an SQL call that exceeds the threshold does not complete
successfully:
SQL call within an API call

The following example shows an SQL call that exceeds the minimum elapsed time threshold,
causing its API call to exceed the threshold as well:

API call
An API call that exceeds the threshold without any corresponding SQL looks like this:
Server Event support for client timeouts

The AR System server adds a server event type for client timeouts. With this feature, a server
event entry is created that provides information about the API call that experienced the timeout.
Client timeouts can be detected with server event workflow, which provides expanded capabilities
for communicating with administrators and users. For example, if a long-running API call caused a
client timeout, server event workflow could email the affected user and notify the administrator
about the details of the timeout.
You enable server event support for client timeouts by selecting Client Timeout on the Server
Events tab of the Admin Console:
The information provided in the Server Event form is tailored to notifications, with fields that can be
easily used in the qualification and as substitution parameters in the notification text. For more
information, see Types of events you can record and Viewing client timeout server event details
(see page 1877).

Server event workflow

The standard BMC Remedy AR System does not include server event workflow, and the client
timeout feature does not provide workflow with the form. The administrator must create the server
event workflow. The following figure shows an example of the filter workflow an administrator might
use to be notified of a user timeout:
Renaming the AR System server

You must scan for AR System server names and rename servers in the following circumstances:
You move your database to a new environment during an upgrade.

You copy a production database to a development or test environment.
You use a standard image to instantiate a virtual machine for BMC Remedy AR System.
You move your existing AR System server into a multitenant mid tier environment, which
requires that each AR System server is uniquely named.
Use the BMC Remedy AR Server Rename utility to rename an AR System server and to ensure
that the server name used by the mid tier and the AR System server is the same.
Using the Rename utility, you can:
Scan the database for the AR System server name

Replace the AR System server name in the following locations:
Specified forms and fields in the database
Specific configuration files and property files
Windows Services and Registries
Repair server name references for BMC Atrium Integration Engine

This topic explains how to use the Rename utility to scan for and replace the server name:
Sequence of server name replacement tasks (see page 331)

Rename utility command and options (see page 331)
Scanning the database for the server name (see page 333)
Replacing the server name in the database (see page 335)
Replacing the server name in files, services, and registry entries (see page 336)
Repairing server name references in BMC Atrium Integration Engine (see page 338)
Sequence of server name replacement tasks

Perform the server name replacement tasks in the following order:
1. Replace the server name in the database. In a server group environment, perform this
operation only on the primary AR System server.
2. Replace the server name in files. In a server group, perform this operation on all servers in
the server group.
3. (Windows only) Replace the server name in the Windows Services and Registries. In a
server group, perform this operation on all servers in the server group.
4. Restart your computer. In a server group, restart the computers on which the primary and
secondary servers are running.
Rename utility command and options

The BMC Remedy AR Server Rename command-line utility ( arsrename .bat or arsrename.sh) is
available in the ARSystemInstallationFolder\ARSystem\artools folder. Use the following
command and its options to run the utility:
arsrename
[-u] [-p] [-a] [-x] [-t] [-timeout]
[-o] [-tokens] [-f] [-fsf] [-fsv] [-ie] [-ief]
The following table describes the arsrename command options, which can be used in any order
in the command.
Option Description
-u Name that identifies the user account for the AR System server
-p Password for the user account
If the user account has no password, use -p "". You can ignore this parameter if the password is empty or blank.
-a Name of the external authentication string or Windows NT domain
This option is related to the Login window's Authentication field. See Authentication String Alias introduction (see
page 1330).
-x Name of the server to connect to

Option Description
-t TCP port number to connect to
If the port number is unknown, use -t 0.
- Time, in seconds, during which the connection must occur, specified in the following format:
timeout
-timeout Normal:Long:XLong
The default values for Normal:Long:XLong are 120:400:1800.
Note: You must specify all three values even if you want to set a single timeout value.
For example, if you want to set the Long timeout value to 600 seconds, use the following command:
-timeout 120:600:1800.
-o Operation code:
1—Scan
2—Replace string tokens
3—Replace string tokens in files
4—Replace string tokens in Windows registry entries
5—Run the Atrium Integration Engine (aiexfer.exe) utility
-tokens List of string tokens in comma-separated value format
-f File path of the CSV file that contains the list of forms and fields for token replacement (required if your operation
code is 3)
While performing a scan operation, use the -f parameter to generate the output CSV file. While performing a
replacement operation, use the -f parameter to pass the input CSV file.
-fsf Whether to use fast scan
Use this option with operation code 1.

Valid values:
0—Off (default)
1—On
-fsv Number of entries to scan
By default, 10,000 entries are scanned.

Valid value: Any positive integer
-ie Whether to use the inclusion-exclusion list of forms in the scan
Valid values:
0—Do not use inclusion-exclusion list
1—Forms specified in the list are scanned along with other forms
2—Only the forms specified in the list are scanned
-ief Path of the inclusion-exclusion list
If the path is not specified or if the value of the -ie option is 1 or 2, the default text file available in the
ARSystemInstallationFolder\ARSystem\artools\etc\arsrename folder is used.

Scanning the database for the server name

Use the Rename utility to scan for the AR System server name or a token string in the database
(Regular forms, character and diary fields). For example, in a multitenant environment, you can
use the utility to scan the database forms and fields for occurrences of the onbmc-s string in the
AR System server name on the myARServer computer. At the command prompt , type the
following command:
arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -tokens "onbmc-s" -f "c:

\data\Output.csv" -timeout 120:600:1800
The output of the scan operation is a CSV file (output.csv) that displays the results of the scan as
a table consisting of the information shown in the following figure and described in the subsequent
table:
output_csv.png
Output of the scan operation
Column Description
Name
Form Name of the regular form in which the AR System server name is found
name
Field ID ID of the character field in which the AR System server name is found
Is Partial (Y Flag that indicates whether the field contains a partial or a complete string of the server name:
/N)? Y—Partial string
N—Whole string
Merge (Y Flag that indicates whether the scanned server name is to be replaced or not; this value is referred to during the
/N)? replace operation
Y—Standard field
N—Custom field; not replaced during replace operation
If you want even the custom fields to be replaced, you must enter Y in the column for the custom field whose server
name value you want to replace.
Special (Y Flag that indicates special handling required during the replace operation
/N)?
Tip
You can use the output generated by the scan operation directly as input for the replace
operation, which replaces the server name in database.

Examples
Use the following command to perform a fast scan for 5,000 entries:
Arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.

csv -fsf 1 -fsv 5000 -tokens onbmc-s
Use the following command to scan only the forms listed the inclusion-exclusion list (a
text file) available at the specified path:
arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -f c:\data\output.

csv -ie 2 -ief C:\<ARSystemInstallationFolder>arsystem\artools\etc\inclusion-
exclusion-list.txt -tokens onbmc-s
Format of the inclusion-exclusion list

You can control the forms that are scanned by creating an inclusion-exclusion text file that contains
the list of forms that you want to include in or exclude from the scan and the qualification that you
want to set for the scan.
The following sample code shows the format of the inclusion-exclusion list:
#--Inclusion list
#----the following qualification is for fetching outgoing messages that are sent
i,AR System Email Messages,'18092'=1 and '18099'=1
#----The following qualification scans only those SRDs which are not closed.
i,SRM:Request,'7'!=9000
#--Exclusion list
e,AR System Server Group Operation Ranking
e,AR System Service Failover Ranking
e,AR System Service Failover Whiteboard
e,ServerStatistics
The following table describes the formats used in this file:
Format Description
# Specifies a comment line

Format Description
i Specifies the inclusion list
e Specifies the exclusion

list
Exclusions from the scan operation

The scan operation ignores the following forms and fields during scanning:
Archive forms
Audit forms
Reserved fields on any regular forms
Core fields with field IDs ranging from 1 to 99 (except field ID 8)
Distributed Server Option (DSO) fields with field IDs ranging from 300 to 322
Dynamic groups with IDs ranging from 60000 to 60999
Special fields
112 (Access control)
179 (GUID)
160 (Locale)
Server Statistics form

AR System API Statistics form
AR System Service Statistics form
AR System Service Statistics Configuration form
AR System Version Control: Object Modification Log form
AR System Version Control: Object Reservation Label form
AP:Detail form
AP:Question-Comment-Info form
Application Pending form
AR System Email Error Logs form
AR System Email Error Messages form
AR System Email Messages form
BPCU-Logs form
Replacing the server name in the database

Use the Rename utility to replace the AR System server name in the database. The replace
operation takes a CSV file as an input and either completely or partially replaces the server names,
depending upon the values specified in the input CSV file. The input.csv file is available in the
AR_SERVER_HOME\artools\etc\arsrename folder.
Notes

The input.csv file contains the information required to replace the server names in
a tabular format with the same columns as the output.csv file.
Use the input.csv file if you have not done any customizations to get the server
name in any base field, overlay, or custom field.
Warning
Do not replace the server name in the following forms:
AR System Server Group Operation Ranking

AR System Service Failover Ranking
AR System Service Failover Whiteboard
In the input.csv file, delete the rows that contain these form names.
The replace operation replaces only those forms or fields that have a Merge flag set to Y in the
input.csv file. To handle special cases, specify Y in the Special (Y/N?) column of the input.csv
file.
As an example, use the following command to replace the onbmc-s string with tenant1-onbmc-s:
arsrename -x myARServer -u Demo -o 2 -tokens "onbmc-s=tenant1-onbmc-s" -f "<C:\Program

Files\BMC Software\ARSystem\artools\etc\arsrename\input.csv>" -timeout 120:600:1800
Replacing the server name in files, services, and registry entries

Use the utility to replace the current server name in the following files of the BMC installed
products, services, and registry entries:
Component Files in which to replace the server name
BMC Remedy AR System

Server AR_SERVER_HOME\ARSystemInstalledConfiguration.xml
AR_SERVER_HOME\conf\ar.cfg
AR_SERVER_HOME\conf\armonitor.cfg
AR_SERVER_HOME\AREmail\EmailDaemon.properties
AR_SERVER_HOME\flashboards\server.conf
AR_SERVER_HOME\pluginsvr\pluginsvr_config.xml
AR_SERVER_HOME\pluginsvr\fts\primary\pluginsvr_config.xml
AR_SERVER_HOME\pluginsvr\fts\secondary\pluginsvr_config.xml
AR_SERVER_HOME\diserver\.kettle\arservers.xml
BMC Atrium Core

ATRIUMCORE_HOME\AtriumCoreInstalledConfiguration.xml
ATRIUMCORE_HOME\cmdb\plugins\ne\pluginsvr_config.xml
ATRIUMCORE_HOME\cmdb\plugins\shared\pluginsvr_config.xml

Component Files in which to replace the server name
ATRIUMCORE_HOME\cmdb\reswift\conf\REConf.properties
BMC Remedy IT Service BMC_REMEDY_ITSM_SUITE_HOME\BMCRemedyITSMSuiteInstalledConfiguration.xml

Management
BMC Remedy Service BMC_SLM_HOME\SLMInstalledConfiguration.xml

Level Management
BMC Remedy Service BMC_SRM_HOME\BMCServiceRequestManagementInstalledConfiguration.xml

Request Management
BMC Remedy Knowledge BMC_RKM_HOME\BmcRkmInstalledConfiguration.xml

Management
BMC Remedy IT Process

Designer BMC_ITSM_PROCESS_DESIGNER_HOME\ProcessDesignerInstalledConfiguration.xml
BMC_ITSM_PROCESS_DESIGNER_HOME\Server\\ARID.xml
Other files on Windows

C:\Windows\System32\drivers\etc\hosts
C:\Program Files\Common Files\AR System\Licenses\server_HostName
If the name of the folder contains the server name, the folder name is replaced. In the
preceding example, the folder name server_HostName gets replaced.
Services
BMC Remedy Action Request System Server server_HostName
BMC Remedy Email Engine - server_HostName 1
BMC Remedy Flashboards Server - server_HostName
Registry entries
HKEY_LOCAL_MACHINE\SOFTWARE\Remedy\ARServer\server_HostName
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Remedy\server_HostName
Examples
Use the following command to replace a server name that contains the onbmc-s string
with tenant1-onbmc-s in AR System and other files:
arsrename -x onbmc-s -o 3 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0
Use the following command to replace a server name that contains the onbmc-s string
with tenant1-onbmc-s in the Windows services and registry entries:
arsrename -x tenant1-onbmc-s -o 4 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p

"" -t 0

Notes
The Rename utility changes the server name in the configuration files, property
files, and XML files. The utility does not change the data in the archive (.arx) files.
Before you run the command to replace server names in the files, ensure that the
following environment variables are defined:
ATRIUMCORE_HOME = D:\BMCSoftware\BMCAtriumCore
BMC_AR_SYSTEM_HOME = D:\BMCSoftware\BMCARSystem
BMC_REMEDY_ITSM_SUITE_HOME = D:\BMCSoftware\BMCITSM
BMC_SERVICE_REQUEST_MANAGEMENT_HOME = D:
\BMCSoftware\BMCSRM
BMC_SLM_HOME = D:\BMCSoftware\BMCSLM
BMC_RKM_HOME = D:\BMCSoftware\BMCRKM
If any of these environment variables is not defined, the server name in the files is not
replaced.
Repairing server name references in BMC Atrium Integration Engine

The BMC Atrium Integration Engine uses the aiexfer.exe utility to repair server name references in
Integration Engine forms and services.
Note
Shut down the BMC Atrium Integration Engine before running the Server Rename utility.
Using the operation code 5 available in the AR Server Rename utility, you can call the aiexfer.exe
utility to repair server name references. The server name passed to this command is the newly
renamed server.
Use the following command:
arsrename -o 5 -x <newARServerName> -u <user> -p <password> -t <port>
For example:
arsrename -o 5 -x newARServer -u Demo -p "" -t 0

Setting Always On logging
This section contains the following topics:
Introduction to the Always On Logging option (see page 339)

Configuring Always On Logging option for BMC AR System server (see page 340)
Important Considerations (see page 341)
Size of the Always On Logging option log file (see page 342)
Introduction to the Always On Logging option

Historically, if you experienced a BMC Remedy AR System server failure, BMC would request you
to enable logging and then wait for the problem to re-occur so that the data could be collected and
then an analysis could be performed.
Now, the Always On Logging option helps you to reduce, and in some cases, eliminate the need to
enable logging. This option allows BMC to immediately perform an analysis and in some cases,
provide a root cause of the failure without having you to enable the logging and wait for the
problem to reoccur. The Always On Logging option helps you identify the root cause of issues
faster and also helps in improving the support for BMC Remedy AR System server.
Enabling the Always On Logging feature logs several types of information. To understand the
different types of log information, see Types of logs . For BMC AR System server, t he Always On
Logging option is enabled by default and is initiated when BMC Remedy AR System server starts.
You can manually enable or disable the option, if required.
Important
For some instances, you may still have to generate additional log files.
Always On Logging option may utilize 5% to 10% excess CPU depending on the
usage of the system. If CPU utilization is around 90%, consider adding extra CPU
capacity.
The size of the allocated buffer impacts heap available for rest of the process. If
you want to increase the buffer size while Always On Logging is enabled, increase
the maximum heap size by the same amount. The usage of heap memory might
increase temporarily. However, the heap size will reset to the original usage after
garbage collector reclaims the unused memory.

You can also enable the Always On Logging option from an user interface.
Configuring Always On Logging option for BMC AR System server

Follow the steps given below to configure the Always On Logging option for BMC AR System
server:
Server Information.
2. Click the Always On Logging tab.
AR System Administration: Server Information form - Always On Logging tab
(Click the image to enalrge it.)
3. In the Always On Logging tab, specify the desired values for the given fields:
a. In the File Name field, enter the log file name along with the location path.
b. In the BufferSize (byte) field, enter the log size (in bytes). The default file size is
5MB.
Important
If you configure the size to 0 MB, the Always On Logging option gets
disabled.
c.
c. In the Errors Triggering Log field, enter the required error code . You can enter
multiple error codes separated by a semicolon. The log file will record all the
information related to the specified error codes. For more information on error codes,
see BMC Remedy AR System error messages (see page 4448).
d. In the Maximum Backups field, enter the number of backup files that you need to
store.
4. Click Apply.
5. Click Ok.
Note
You can use the Save to File button to generate logs as and when desired. You need not
wait for an error to occur and a log file to be generated. The Save to File button can be
safely used to monitor the progress/performance of BMC AR System server.
Important Considerations
The Always On Logging option ensures the following:
A minimum set of logs is always available either on-demand or at the time of an issue like a
server or an operation failure.
If you have not enabled the server-side logging and the BMC Remedy AR System server
failure occurs or any other server related issues occur, the Always On Logging option
provides a snapshot of the most recent activity in the server. This snapshot is saved into a
file for review and analysis.
In a server group environment, ARGetServerInfo (GSI) having the operation number 430
saves the logging information for all the servers in the group. The logging information is
saved for the server, its plug in server contents, and the thread stack traces of all the
processes associated with the respective server.
If the BMC Remedy AR System server failure occurs, it automatically takes a snapshot.
Alternatively, you can also manually trigger a snapshot for other events.
The Maintenance Utility Log Zipper also collects these logs. You can dump the log file and
use the Log Zipper to send a single zip file.
Note
The BMC Remedy AR System server automatically runs the Always On Logging
option. Logging information using this option is independent of the existing logging.
The Always On Logging option does not save the log file information for ordinary
shutdown options like arsystem stop or a Microsoft Windows stop service.
You must collect the logging information from the BMC Remedy AR System server’
s \db directory, as the log file does not have a View button.

When you enable the Always On Logging option, the logging information is saved on the following
conditions:
1. On Demand: You can choose when to save the log information as required. This is
applicable to server group environments as well.
2. On Error condition : This option checks if the error exists in the configured error list and
only then save the buffer content in a log file. In a server group environment, logging
information is saved on the server on which the error occurred.
Size of the Always On Logging option log file

Always On Logging option allows you to configure the log file size. The log file size is configured
using the BufferSize parameter. The default size of the log file is 5 MB.
Note
The size of the log file will not be same as the specified buffer size. The actual size of the
generated log file will be approximately half the size of the specified buffer size. For
example, if you specify the buffer size as 5MB, the log file generated will be roughly
around 2.5MB.
Related topics
To enable Always On Logging for plug-in server, see Setting plug-in server options (see page 364).
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 Atrium Integration Engine
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 (see page 489).
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 (see page ).
The following topics provide detailed information about how to configure server groups:
Configuring the server group check interval (see page 344)

Setting failover rankings for servers and operations (see page 345)
Signaling mechanism in a server group (see page 347)
Configuring full text search for a server group (see page 349)
Configuring the Email Engine for a server group (see page 353)
Configuring flashboards for server groups (see page 353)
Bypassing the load balancer to work on a specific server (see page 354)
Using data archiving with server groups (see page 355)
Configuring logging for server groups (see page 355)
Removing a server from a server group or remove an unused server name (see page 356)
Sharing a database without using a server group (see page 356)
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
(see page 347).
Checking server group status and reporting status generates a certain amount of database traffic,
so you should tune this setting to balance the time to failover against the frequency of posting the
check and query to the database.
To set the Check Interval
1. Open the AR System Administration: Server Information form.
2.
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 (see
page 345).
4. Click OK.
5. Restart each server in the server group.
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.
Guidelines to set operation rankings for the server group

Use the following guidelines to determine how to set operation rankings for the server group:
The servers for any one operation are ranked lowest to highest. A value of 1 indicates the
server chosen first to perform the operation. The next highest value indicates the server that
takes over the operation if the first server fails, and so on.
Ranking numbers do not need to be consecutive.
If a value is null, the server ignores the entry.
If an operation has no server designated with a valid rank, it is not run on any of the servers
in the group.
Avoid assigning two servers the same ranking for the same operation. (For ease of
configuration, the form enables you to do this temporarily.)
Operations can be spread freely across different servers, with the exception of operations
involving BMC Remedy Approval Server, BMC Atrium CMDB, and the BMC Service Level
Management engine (labeled Business Rules Engine in the form). These operations must
reside on the same server as the administration operation; therefore, the operations must
have the same ranking as the administration operation so that they move as a unit.
If you are implementing full text search (FTS), an additional restriction for multi-platform
server groups exists. The Administration and Full Text Indexing operations must be
restricted to server group nodes that can have a compatible directory structure for the
Search Server configuration files.
To establish operation rankings in the server group
1. In a browser, log on as a user with Administrator privileges to any server in the group.
2.
2. Open the AR System Server Group Operation Ranking form in search mode.
http://<midTierServer>:<portNumber>/arsys/forms/
<ARSystemServer>/AR+System+Server+Group+Operation+Ranking/
3. Perform an unqualified search to see the entries in the form.
4. Modify entries as required to construct a fail-over hierarchy for ownership of operations.
5. Save the AR System Server Group Operation Ranking form.
6. Restart all the AR System servers in the group.
Delinquent threshold
The Delinquent Threshold field determines the number of times the specified server can miss
reporting its status before the next server in the ranking takes responsibility for the operation. This
setting works together with the Check Interval to determine the total time to failover for any
operation.
Signaling mechanism in a server group

Starting from version 9.0, BMC Remedy AR System servers use Java Messaging Service (see
page 347) (JMS) or Remote Method Invocation (see page 348) (RMI) mechanism to communicate
with other servers in the group. Servers determine the active status of all other servers in the
server group by using the Heartbeat mechanism (see page 348).
Note
For Java servers, arsignald process is not used for communication in a server group.
JMS message
When a server needs to communicate with the other servers in the group to process a request, the
following actions occur:
Sever sends JMS to the coordinator server for the specific request.
The coordinator server fetches information from the ranking form about the servers that
need to be notified.
The coordinator server sends JMS message to notify the servers to process the request.
This type of communication is used in operations such as Full Text Search (FTS), application
pending messages (for example, Approval, Atrium Integrator). JMS messages are also used to
notify servers when a user logs out, releasing a fixed or floating license on a server in the server
group.
For more information on the AR System Server Group Operation Ranking form, see Setting
failover rankings for servers and operations.
Example

Consider a server group with three servers, S1, S2 (coordinator server), and S3.
When performing an FTS operation, suppose a user creates an entry with FTS fields, which is
picked by server S1, a non-FTS sever. Sever S1 then sends JMS to the coordinator server S2.
Sever S2 checks the ranking form and notifies server S3 to process the operation.
Remote Method Invocation

Java server uses Ehcache to hold metadata object cache in memory. For a server group, only the
server designated as an administrator server is allowed to modify the metadata. When metadata is
modified in the administrator server, Ehcache is updated. Ehcache is configured to communicate
these changes to other servers in a server group by means of RMI calls so that the other servers
also update their in-memory metadata cache.
Heartbeat mechanism
The heartbeat mechanism enables a server to determine the active status of all other servers in a
server group. Each server in the group updates the servgrp_board table in the database to
notify its availability. Heartbeat mechanism is also used during the startup of the server or when a
new server is added to the server group.
For more information on servgrp_board table, see Table support for server group tables (see page
2036).

Configuring full text search for a server group

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 (see page 349)

Configuring FTS for a server group (see page 350)
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 core – manages the FTS functionality using Lucene library

FTS Indexer – part of AR System server
FTS Searcher – part of AR System server and FTS Plug-in server
FTS plug-in — a Java plug-in, which runs under the FTS Plugin server to serve search
requests from the remote AR System servers (which are not indexer servers) in the server
group.
Index – Lucene index files
As events occur within AR System that cause data to be indexed, the AR System server sends a
message to FTS Indexer which then adds, deletes, or updates data within the index. Other events
could include a request to search the index.
If AR System server is not the indexer in a server group, the AR System server sends the search
request to the FTS plug-in which is running under remote FTS plug-in server on the indexer server
(where the index exists). The remote FTS plug-in server returns the search results to AR System
server and then the AR System server processes the data accordingly.
If AR System server is the indexer, it performs the search requests locally in the index and then
returns the search results to the client.
When you configure a server group for FTS, ensure that the following conditions are met:
The required number of servers are designated as FTS indexing servers in the server
group.
The FTS indexing server is the AR System server that also has the FTS collection and
conf directories located on a local disk.
The FTS indexing server hosts a FTS plug-in server for serving the search requests from
the remote AR System servers that are not designated as indexer server.
You can designate a server as the FTS indexing server by ranking it in the AR System Server
Group Operation Ranking form. For more information, see Setting failover rankings for servers and
operations (see page 345).

FTS uses only one plug-in server as the reader (searcher). The reader plug-in is installed on the
FTS indexing server. Only the designated indexing FTS server has a ranking entry in the AR
System Server Group Operation Ranking form. This AR System server acts as FTS indexer and
FTS searcher for local search requests. The reader (searcher) FTS plug-in server serves as the
searcher for all the other AR System servers in the server group that are not designated as
indexing server, so you must configure all other non-indexing servers to connect to the searcher
FTS plug-in server instance running on the FTS indexing server. The searcher 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 the 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. For more information, see FTS plug-in
configuration (see page 735). There is no search fail-over for the indexer AR System server.
Configuring FTS for a server group

If you use FTS in a server group, you can designate more than one server as indexing server in
the server group.
Each 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 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 (see page 345).
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.
> General > FTS Configuration.
3.
3. Complete the form as per FTS Configuration form in the AR System Administration Console
(see page 552).
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 (see
page 1815).
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.
2. On the Basic panel of each distributed mapping, select the Allow Any Server in Server
Group check box.
This setting indicates to the servers in the group that regardless of the source (From) server
name specified in the mapping, any server in the group is qualified to be the source server.
In the event of a fail-over where the distributed operation moves from one server to another,
the data continues to be processed.
Related topics
DSO for load balancing (see page 544)
Enabling DSO on an AR System server (see page 536)
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 AR System Configuration Generic UI
form to the same port number. See Configuration settings S-Z (see page 1226).
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.
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 port number in the AR System Administration: AR
System Configuration Generic UI form to the same port number.
The syntax is as follows: Server-Group-Flashboards-Admin-Port: 2021.
See Updating configuration settings by using the AR System Configuration Generic UI form (see
page 1235).
This enables the server to communicate flashboards administration information to the flashboards
server during server group processing.
Bypassing the load balancer to work on a specific server

To change object definitions and workflow on the administrative server in a load-balanced
environment, you must bypass the load balancer to connect to the administrative server with BMC
Remedy Developer Studio. The same consideration applies when you must make configuration
changes on a specific server in the group in a browser.
To do this, you can connect to the server by using the unique server name rather than the load
balancer name (which is the same as the common server name alias for the group).
To ensure that the server recognizes references to itself as the current server while designing
workflow and applications, add the IP Name setting to the configuration file. This setting indicates
to the server that any of a given set of server names is recognized as the current server. You might
need to designate a short name and a long name for each server as shown in the following
example:
IP-Name: serverA

IP-Name: serverA.remedy.com
If BMC Remedy Developer Studio used either of these server names to log in, that server is
recognized as the current server in workflow.
Using data archiving with server groups

By default, the data archiving feature is enabled on an AR System server. To disable archiving for
all forms on a server, select the Disable Archive option on the Configuration tab of the AR
System Administration: Server Information form.
For a server group, you can disable archiving on all the servers except one if you want archiving to
take place on only one server. To do this, configure the server group in the AR System Server
Group Operation Ranking form to make sure that only one server performs the archiving operation.
Configuring logging for server groups

Information tracked in the server group log file includes the starting and stopping of operations, the
evaluation of other servers, and the timing of each event. The arsignald log file tracks the startup
and shutdown of the arsignald daemon and all signals sent between servers in the group.
To turn on the server group and arsignald log files
1. Open the AR System Administration: Server Information form, and click the Log Files tab.
2. Select the logging to use:
For server group logging, select the Server Group Log check box.
For arsignald logging, select the ARSIGNALD Log check box.
3. Enter a path for each log file if you do not want to use the default paths.
4. Click OK.
To log server group activity in the Server Events form
1. Open the AR System Administration: Server Information form, and click the Server Events
tab.
2. Select the Server Group Actions check box.
3. Click OK.
Note
You cannot log arsignald activity in the Server Events form.

Removing a server from a server group or remove an unused

server name
To remove a server from a server group
1. Open the AR System Administration: Server Information form, and click the Configuration
tab.
2. Clear the Server Group Member check box.
3. Restart the server.
To remove an unused server name
1. Open the AR System Server Group Operation Ranking form, and remove all the entries for
the server name.
2. Restart one of the servers in the server group.
The server that you restarted removes all the server group references for a server that does not
have any ranking entries.
Sharing a database without using a server group

The recommended way to share a database is to create a server group. Alternatively, you can
configure two or more AR System servers to share the same database without making them
members of a server group. In this case, automatic failover protection is unavailable, and when you
change object definitions, you must manually refresh the cache on other servers in the group (for
example, by restarting them).
This approach can be sufficient for managing performance. For example, you can use a shared
database in an environment where the user traffic all goes to one AR System server. In this
scenario, you can use another server on the same database to handle tasks such as reporting or
reconciliation, which can have a performance impact on the AR System server.
When you share a database without using a server group, you must designate one server as the
administrative server by disabling administrative functions on the other servers sharing the
database. Also note that specific services can only be running on one system at a time, and in
some cases, additional configuration is required to manage them (that is, escalations need to be
disabled on all but one server and the assignment engine should only run on one server).
To share a database between AR System servers without using a server group, perform the
following installation and configuration steps:
During installation
Select the Overwrite or Upgrade option for the first server installed.

Select the Server Group option when installing subsequent servers that share the same
database.
Specify the same database information for all servers that share the database.
Note
Choosing Server Group during AR System installation does not configure the
servers as members of a server group. It merely indicates to the installer that the
server shares the database with an existing AR System server, with or without
server group membership.
After installation
Determine which server is the administrative server, where you manage and modify forms,
workflow, and applications with BMC Remedy Developer Studio.
Isolate BMC Remedy Developer Studio access, escalations, and archiving to the
administrative server.
To turn off Developer Studio access, escalations, and archiving on the non-
administrative servers (without server groups)
1. In a browser, log on to each of the non-administrative servers as a user who is a member of

the Administrator group.
2. Click AR System Administration Console > System > General > Server Information .
3. Click the Configuration tab, and select the following check boxes:
Disable Admin Operations
Disable Escalations
Disable Archiving
Configuring java plug-in servers

You can use the AR System Administration:Plugin Server Config form to display information about
the Java plug-in servers. As an administrator, you can access this form from the BMC Remedy AR
System Administration Console.
Note
The AR System Administration:Plugin Server Config form is for Java plug-in servers only.
You cannot use this form to configure native plug-in servers.

The following table lists the common fields on the AR System Administration:Plugin Server Config
form:
Field name Description Reference
Plugin Server Select a plug-in server instance from the list of available plug-in server
Instance instances .
Plugin Server Enter the path where the selected plug-in server instance is running.
Instance Path
Plugin Set Select a plug-in set from the list. Creating Java plug-in sets
(see page 359)
This property enables you to load multiple plug-ins that share a common
parent class loader.
Note: The Plugin Set Configuration tab (see page ) is visible only if
you select a value for this field.
Plugin Server Host Enter the host name of the computer where the selected plug-in server
instance is running.
The following table lists the tabs in the AR System Administration:Plugin Server Config form. The
information provided in each tab is described in the sections that follow.
Tab Information Reference
Global Plugin Server Enables you to configure the default plugin server settings Setting global plug-in server options
Configurations (see page 359)
Plugin Server Enables you to create and configure the plug-in server settings Setting plugin server configuration
Configuration options (see page 361)
Note: These settings override the settings defined in the
Global Plugin Server Configurations tab.
Plugin Configuration Enables you to view, create, modify, and delete plug-ins and Working with Java plug-ins (see
their configurations page 365)
Plugin Set Enables you to view, create, modify, and delete plug-in sets Working with Java plug-in sets (see
Configuration and their configurations page 367)
Note: This tab is visible only after you add a plug-in set (see
page 358).
Note
If you modify the Java plug-in server configuration data, you must restart the Java plug-in
server for the changes to take effect.

Related topics
Centralized configuration (see page 1144)
Troubleshooting issues with plug-in servers (see page 4694)
Creating Java plug-in sets

> General > Plugin Server Configuration.
2. On the AR System Administration:Plugin Server Config form, click the plus sign to open the
Create Plugin Set form.
3. Enter the values for the following fields, and click Create:
Plugin Instance This field is populated with the value from the Plugin Server Instance
field.
Plugin Set Enter the name of the plug-in set.
Related topics
Centralized configuration
Troubleshooting issues with plug-in servers
Setting global plug-in server options

Use the Global Plugin Server Configurations tab to create global settings for the plug-in servers.
These settings apply when the plug-in server options in Setting plug-in server options (see page
359) are not specified.
2. In the AR System Administration:Plugin Server Config form, click the Global Plugin Server
Configurations tab.
3. Edit the options listed in the following table as needed.
General Register Specifies whether you want the Java plug-in to register with the portmapper
Configurations With Valid values:
PortMapper true
false (default)
Threads Max Threads The maximum number of threads allowed in the thread pool. This is for worker
Configurations threads of plug-in servers.
Default: 10
Global default: 30

Number Of Specifies the total number of core worker threads that the Java plug-in server
Core initializes to process various RPC requests
Threads Valid value: Any positive integer
Default: 5
Global default: 30
Number Of Specifies the total number of selector threads that the Java plug-in server uses to
Selector dispatch RPC requests to the core worker thread task queue
Default: 2
Global default: 5
Encryption Encryption Determines whether the plug-in server allows or requires encrypted communication
Configurations Policy with the AR System server
Valid values:
0 - Allowed but not required
1 - Required
2 - Not allowed (default)
Data Determines the network data encryption algorithm that the plug-in server uses to
Encryption communicate with its clients
Algorithm Valid values:
1 - RSA low encryption, modulus 512 bits (default)
2 - RSA medium encryption, modulus 1024 bits (requires BMC Remedy
Encryption Performance Security)
3 - RSA high encryption, modulus 2048 bits (requires BMC Remedy
Encryption Premium Security)
Note: If the value of the Encryption Policy option is set to 2, this option is ignored.
Data Key Specifies the expiration time for the network data encryption key
Expiry Valid value: Any positive integer
Default: 2700 (seconds)
Public Key Specifies the publickey-privatekey encryption algorithm that the plug-in server uses to
Algorithm communicate with its clients
Valid values:
Public Key Specifies the expiration time for public key

Default: 86400 (seconds).
Other Work Queue Specifies the interval at which the core worker thread task queue monitor checks
Configurations Monitor Log whether the tasks in the queue exceed the threshold set for the Work Queue Task
Interval Threshold option
Valid value: Any positive integer (milliseconds)
Default: 0

Excess Specifies the maximum time that the excess idle threads will wait for a new task
Core before terminating
Threads Idle Valid value: Any positive integer (milliseconds)
Keep Alive Default: 0 (unlimited time)
Time
Reload Specifies the interval between the time that you add a plug-in configuration and the
Delay time that the system dynamically loads and initiates the plug-in
During this interval, you can modify the new plug-in configuration if necessary without
restarting the plug-in server. After the system dynamically loads and initiates the plug-
in, any changes you make to the plug-in configuration require a plug-in server restart.
Default: 30000 ms
Work Queue Specifies the threshold for the core worker thread task queue. When the tasks in the
Task queue exceed this number, a message is logged in the arjavaplugin.log file.
Threshold Valid value: Any positive integer
Default: 5
Note: If the value of the Work Queue Monitor Log Interval option is set to 0, this
threshold is ignored.
Native Enable Routes the AREAVerifyLogin calls to the Native Plugin Server through a bridge
Configurations Native Valid values:
Bridge true
false (default)
4. To save the changes, click Apply, or click Reset to restore the default values.
Related topics

Setting plugin server configuration options

Use the Plugin Server Configuration tab to create settings for the plug-in server instance. The
settings on this tab supersede the global plug-in server settings (see page 359).
2. Select a Plugin Server Instance.
3. Click the Plugin Server Configuration tab
4. Edit the options listed in the following table, as needed:
General Plugin Port Specifies the TCP port number where the Java plug-in server runs
Configurations You enter this port when you install the AR System server, which sets the value of
the Server-Plugin-Alias property in the ar.cfg or ar.conf file.
Note: If you have a single plug-in server instance, you can enter this value in the
Plug-in Server list on the Connection Settings tab of the AR System
Administration:Server Information form.

Valid values: Unused port numbers from 1024 to 64000

Default: 9999
Register With Specifies whether you want the Java plug-in to register with the portmapper
PortMapper Valid values:
True
False (default)
Masking (Optional) Enables plug-in developers to implement the com.bmc.arsys.pluginsvr.

Implementation ISignalMasking interface to enable a plug-in server to use custom signals
Note: This option is for internal use only.
Example: com.bmc.arsys.plugins.signal.
SignalMaskForSpecificPlugins
Encryption Encryption Determines whether the plug-in server allows or requires encrypted communication
Configurations policy with the AR System server
Valid values:
0 - Allowed but not required
1 - Required
2 - Not allowed (default)
Data Determines the network data encryption algorithm that the plug-in server uses to
Encryption communicate with its clients
Algorithm Valid values:
Note: If the value of Encryption Policy is set to 2, this option is ignored.
Data Key Specifies the expiration time for the network data encryption key
Expiry Valid value is any positive integer. The default is 2700 (in seconds).
Public Key Specifies the publickey-privatekey encryption algorithm that the plug-in server uses
Algorithm to communicate with its clients
Valid values:
Public Key Specifies the expiration time for public key

Default: 86400 (seconds)
Threads Max Threads The maximum number of worker threads allowed in the thread pool of plug-in
Configurations servers
Default: 10
Global default: 30
Number Of Specifies the total number of core worker threads that the Java plug-in server
Core Threads initializes to process various RPC requests


Default: 5
Number Of Specifies the total number of selector threads that the Java plug-in server uses to
Selector dispatch RPC requests to the core worker thread task queue
Default: 2
Other Work Queue Specifies the interval at which the core worker thread task queue monitor checks
Configurations Monitor Log whether the tasks in the queue exceed the threshold set for Work Queue Task
Interval Threshold
Default: 0
Excess Core Specifies the maximum time that the excess idle threads waits for a new task
Threads Idle before terminating
Keep Alive Valid value: Any positive integer (milliseconds)
Time Default: 0 (unlimited time)
Reload Delay Specifies the interval between adding a plug-in configuration and the system
dynamically loading and initiating the plug-in
During this interval, you can modify the new plug-in configuration if necessary
without restarting the plug-in server. After the system dynamically loads and
initiates the plug-in, any changes that you make to the plug-in configuration require
a plug-in server restart.
Default: 30000 ms
Work Queue Specifies the threshold for the core worker thread task queue
Task When the tasks in the queue exceed this number, a message is logged in the
Threshold arjavaplugin.log file.
Default: 5
Note: If the value of Work Queue Monitor Log Interval(mSec) is set to 0, this
threshold is ignored.
Logging To understand the concept of configuring plug-in server logging, see BMC Remedy AR System
Configurations Plugin server logging feature and its value. .
For a quick demo on how to configure plug-in server logging, see BMC Remedy AR System
Plugin server logging feature. .
Note: The videos are recorded using the earlier version of BMC Remedy AR System. So the UI
displayed in the videos may differ than the UI available for BMC Remedy AR System 9.1.
Enable Plugin The setting that determines whether logging is turned on. The available values are
Log as follows:
False
True
To enable logging, select True.
Parameters added to the pluginsvr_config.xml file: pluginSvrLogEnable
Log File The absolute path and the name of the log file.
For example, C:/Program Files/BMC Software/ARSystem/89/ARServer/Db
/arjavaplugin.log
Note: You can change the name of the log file.
Parameters added to the pluginsvr_config.xml file: pluginSvrLogFile
Log Level

This setting determine the types of messages that are logged for the calls. The
following different types of log levels are available
TRACE
DEBUG
INFO
WARN
ERROR
FATAL
Parameters added to the pluginsvr_config.xml file: pluginSvrLogLevel
Maximum Log The maximum size (in bytes) a log file can reach before an automatic backup copy
File Size is made. The backup copy is made with the same file name and an incremental
number. The default size is 5242880 bytes (5 MB) . Parameters added to the
pluginsvr_config.xml file: pluginSvrLogMaxFileSize
Log History The maximum number of backup files that the system will save. A backup file is
generated any time the log file size reaches the limit specified in the Maximum Log
File Size parameter. The default value is 10. Parameters added to the
pluginsvr_config.xml file: pluginSvrLogMaxHistory
Native Enable Native Routes the AREAVerifyLogin calls to the Native Plugin Server through a bridge
Configurations Bridge Valid values:
True
False (default)
Always On Log File The absolute path and the name of the log file.
For example, C:\temp\ao.log
Note: You can change the name of the log file.
Buffer Size Size of the log file in bytes.

Note:
If you configure the size to 0 MB, the Always On Logging option gets disabled.
Number of Number of backup files that you need to store

Copies
5. To save the changes, click Apply, or click Reset to restore the default values.
6. (Optional) To copy the global settings for the selected plug-in server, click Copy Global.
Note
When you configure plugin server logging, the logging parameters are saved in
the Pluginsvr_config.xml file. The logging configuration changes are applied
immediately; you do not have to restart the plug-in server.
To apply changes to configuration settings other than logging configuration, you
must restart the plug-in server.

Related topics

Working with Java plug-ins

Use the Plugin Configuration tab to create (see page 365), view (see page 366), or modify (see
page 366) plug-ins and their configuration settings.
Note
When you create a new plug-in, it is loaded dynamically. You do not need to restart the
AR System server.
To create a Java plug-in
2. On the AR System Administration:Plugin Server Config form, open the Plugin
Configuration tab, and click Create to open the Create New Plugin form.
3. Enter values for the following fields, and click OK:
Plugin Name Enter the name of the plug-in.
Plugin Class Enter the name of the Java class that will implement the plug-in.
Name
Value: Any valid class name from the JAR file
Plugin File Enter the name of the file that the plug-in server loads to access the plug-in implementation.
Name
Note: This file is located in the plug-in server class path.
Value: The absolute file name of the JAR file that contains the class that contains the plug-in implementation
and all the dependent JAR files
AR Server Enter the AR System server name where the Server-Plugin-Alias entry will be created.
Create Server Select the check box to create the Server-Plugin-Alias entry in the AR System Configuration Component
Plugin Alias Setting form. Note: For the AR System server to communicate with the Java plug-in, you must create the
Entry in Server-Plugin-Alias entry in the AR System Configuration Component Setting form.
ARServer
Path Elements Click the plus sign and enter the location of a dependent JAR file or the path to a dependent native library.
Each plug-in element can contain zero or more pathelement elements.
User Defined (Optional) Click the plus sign and enter the user-defined configuration elements:
Elements

Setting Name — Name of the user defined element.

The syntax for this element is:
pluginName.userDefined.settingName
Note: pluginName is automatically populated based on the value entered in the Plugin Name field.
Setting Value — Value for the element.
Note:
You must define values for both Setting Name and Setting Value.
If you add two values for the same Setting Name, only the first value is applicable.
To view a Java plug-in
2. On the AR System Administration:Plugin Server Config Form form, open the Plugin
Configuration tab.
Plugins Displays the list of available plug-ins
Plugin Class Displays the name of the Java class in the JAR file that implements the plug-in
Name
Plugin File Enter the name of the file that the plug-in server loads to access the plug-in implementation.
Name Note: This file is located in the plug-in server class path.
Value: The absolute file name of the JAR file that contains the class that contains the plug-in
implementation and all the dependent jar files.
Path Elements Displays the location of the dependent JAR file or the path of the dependent native library
User Defined (Optional) Displays the user-defined configuration elements for the selected plug-in
Elements
To modify a Java plug-in
2. On the AR System Administration: Plugin Server Config form, open the Plugin
Configuration tab.
3. In the Plugins list, select the plug-in that you want to modify.
4. Click Modify to open the Modify Existing Plugin form.
5. Modify the data as needed, and click OK.
To delete a Java plug-in
2.
2. On the AR System Administration:Plugin Server Config Form form, open the Plugin
Configuration tab.
3. In the Plugins list, select the plug-in that you want to delete, and click Delete.
4. In the confirmation box, click Confirm.
Note
You must restart the Java plug-in server for these changes to take effect.
Related topics

Working with Java plug-in sets

Use the Plugin Set Configuration tab to add (see page 367), view (see page 368), or modify (see
page 368) plug-in sets and their configuration settings.
Note
The Plugin Set Configuration tab is visible only if you select a value for the Plugin Set
(see page 358) field.
To add Java plug-in set configurations
2. On the AR System Administration:Plugin Server Config form, open the Plugin Set
Configuration tab, and click Create to open the Create\Modify Plugin Set Configuration
form.
3. Enter the values for the following fields, and click Create:
Field Description
name
Key Prefix Enter the key prefix by using the following format:
pluginSetName.pathelement.type
pluginSetName must match the name in Creating Java plug-in sets (see page 359).
Key Type location or path.
Value

Field Description
name
If you entered location in the Key field, enter the complete path to the JAR file.
For example: D:\BMCSoftware\BMCARSystem\pluginsvr\rle\lib\aspectjrt.jar
If you entered path in the Key field, enter the path of the folder that contains the JAR file.
For example: D:\BMCSoftware\BMCARSystem\pluginsvr\chg
Note
There is no validation for the values you enter in the Key and Value fields. The plugin
server validates this internally. If these values are incorrect, they are not saved in the
pluginsvr_config.xml file. There is no error message logged in the arjavaplugin.log or
arplugin.log files either.
To view Java plug-in set configurations
Configuration tab.
The Plugin Set Path Elements area displays the list of available plug-in sets with their
values.
To modify Java plug-in set configurations
Configuration tab.
3. In the Plugin Set Path Elements list, select the plug-in set that you want to modify.
4. Click Modify to open the Create\Modify Plugin Set Configuration form.
5. Modify the data as needed, and click Update.
To delete Java plug-in set configurations
2. On the AR System Administration:Plugin Server Config Form form, open the Plugin Set
Configuration tab.
3. In the Plugin Set Path Elements list, select the plug-in set that you want to delete, and
click Delete.
4. In the confirmation box, click Confirm.

Related topics

BMC Remedy AR System cache management

The following topics provide detailed information about BMC Remedy AR System cache
management:
Configuring the server cache (see page 369)

Guidelines for resolving cache memory issues (see page 373)
Running the ViewStat utility (see page 376)
Setting the distributed mapping cache refresh interval (see page 377)
Setting the distributed mapping cache refresh interval 9.1 (see page 377)
Actions that trigger cache events (see page 378)
Mid Tier cache configuration (see page 381)
Actions in ITSM 7.0.00 applications that trigger caching (see page 392)
Configuring the server cache

The following topics provide information about configuring the server cache:
Configuring cache load options (see page 369)

Configuring the AR System server to maximize memory use (see page 372)
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 (see page 369)

Caching display properties (see page 372)
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.
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 (see page ).
Cache-Mode For details about this setting, see Cache-Mode (see page ).
Max-Entries-Per-Query For details about this setting, see Max-Entries-Per-Query (see page ) .
Cache-Display-Properties For details about this setting, see Cache-Display-Properties (see page )
.
Disable-ARSignals For details about this setting, see Disable-ARSignals (see page ).
Note
For more information about configuring cache properties to maximize memory utilization,
see Guidelines for resolving cache memory issues (see page 373).
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 (see page 373)

Avoid making administrative changes during peak hours (see page 374)
Configuring the AR System server to control memory use (see page 374)
BMC Remedy AR System caching (see page 375)
Checking the BMC Remedy AR System log files for long-running operations (see page 376)
For more information on resolving cache memory issues, see the blog Memory leak shared on
BMC Communities.
Improving the AR System server startup time

BMC improved the startup time of the BMC Remedy AR System server as follows:

For Release 7.5.00 and 7.1.00 patch 007, data is now stored in the field_dispprop table so
that it can be read from and written to more efficiently. For more information, see The field
table in the AR System data dictionary (see page ).
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 (see page 369).
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 (see page )) 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 (see page 392)).
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 (see page 372)).

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:
Client cache loads (see page 375)

Server cache loads (see page 375)
For details about activities that can trigger a re-cache, see Actions that trigger cache events (see
page ).
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 (see page 387).
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 (see page
)).

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.
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.
Running the ViewStat utility

After you upgrade to BMC Remedy AR System 9.1 from the earlier versions you see performance
issues while accessing the forms or views. BMC recommends to use the Java based utility to
generate a new viewstat file that will allow most efficient use of mid-tier's memory cache and the
best form access performance for the end users.
To run viewstat utility
1. Stop the Tomcat server for the previously installed versions of BMC Remedy AR System
server.
2. Copy the viewstat file from C:\Program Files\BMC Software\ARSystem\midtier\WEB-
INF\classes to any location on the local drive of your computer. For example C:\viewstat.
dat
Note

You should copy the viewstat file from the previously installed version of BMC
Remedy AR System.
3. Run the viewstat utility using the following command:
C:\Program Files\BMC Software\ARSystem\midtier\tools\viewstat>run.bat "C:

\viewstat" <server-name>
The Command prompt displays the following message:

Viewstat migrated successfully , New file created C:
\viewstat\viewStats_<server-name>.dat
4. Copy the newly created file to the following location:
C:\Program Files\BMC Software\ARSystem\midtier\WEB-INF\classes\viewServerStats
5. Restart the Tomcat server.
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.
2. Click the DSO tab.
3. In the Cache Check Interval field, enter a refresh interval in seconds. The maximum value
is 43200 seconds (12 hours).
The corresponding entry in the BMC Remedy AR System server configuration file is DSO-
Cache-Check-Interval.
4. Click OK.
The change takes effect immediately. You do not need to restart the BMC Remedy AR
System server.
Setting the distributed mapping cache refresh interval 9.1

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 AR System Configuration Generic UI form (For more
information, see Updating configuration settings by using the AR System Configuration Generic UI
form (see page 1235)).

To set the distributed cache refresh interval
1. Open the BMC Remedy AR System Administration: Server Information form for the local
3. In the Cache Check Interval field, enter a refresh interval in seconds. The maximum value
is 43200 seconds (12 hours). The corresponding entry in the AR System Configuration
Generic UI form is DSO-Cache-Check-Interval.
4. Click OK. The change takes effect immediately. You do not need to restart the BMC
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 (see page 378)
Actions that trigger cache or re-cache events (see page 378)
Reducing memory using Display Property Caching (see page 380)
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 (see page 375)).
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 (see page 375)).
Admin Copy Cache — The AR System server creates an administrative copy of its cache
for any administrative change.
Actions that trigger cache or re-cache events
Note
For details about mid-tier caching, see Actions that affect mid tier caching (see page )
.
Actions that trigger cache or re-cache events

Action Client re-cache Server re- Admin copy

cache 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 (see page 380), 9 (see NO NO

page 380)
Remove a group from the Group List in the User form NO 5 (see page 380) NO YES
Add a user to a group YES 3 (see page 380),9 (see NO NO

page 380)
Remove a user from a group YES 3 (see page 380),9 (see NO NO

page 380)
Add a computed group YES 3 (see page 380),8 (see NO NO

page 380)
Add a group to a computed group YES 3 (see page 380),8 (see YES NO
page 380)
Remove a group from a computed group YES 3 (see page 380),8 (see YES NO
page 380)
Add a user to a group that is part of a computed group YES 3 (see page 380),8 (see NO YES
page 380)
Remove a user from a group that is part of a computed group YES 3 (see page 380),8 (see NO NO
page 380)
arsignal -a NO NO NO
arsignal -b NO YES NO
arsignal -c NO NO NO
arsignal -e NO NO YES
arsignal -g NO 4 (see page 380) 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 (see page 380),4 (see YES YES

page 380)
Create, modify, or delete an application NO NO YES
Create, modify, or delete an active link YES 2 (see page 380) NO YES

Action Client re-cache Server re- Admin copy

cache cache
Create, modify, or delete an active link guide NO NO YES
Create, modify, or delete an entry in the Group form (not every NO NO YES 6 (see
field must be affected) page 380)
Create, modify, or delete an entry in the Role Mapping form (not NO NO YES 6 (see
necessarily every field) page 380)
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 (see page 380) NO YES
Create, modify, or delete a menu NO 3 (see page 380) NO 3 (see YES

page 380)
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 (see page 291), Display Property Caching (see
page ).
Note
The Cache only server display properties setting might impact performance when
display properties are requested, but the impact is not significant.
Mid Tier cache configuration

The following topics provide information about configuring the BMC Remedy Mid Tier cache:
About Mid Tier caching (see page 381)

About browser cache (see page 384)
BMC Remedy Mid Tier recommendations (see page 387)
Actions that affect mid tier caching (see page 391)
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 (see page 382).
Note
While you upgrade BMC Remedy Mid Tier, if the cache version number changes, the
catalina.out file logs the following message, and BMC Remedy Mid Tier rebuilds the
cache:
CACHE: SetupServlet:init: Version change is detected due.

Older version = 0 New version = 5 Cache has to be flushed and rebuild
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 (see page ).
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 (see page 443).
Note
-- The Sync cache option is not available for 7.1.0 and prior releases.
-- When you restart BMC Remedy Mid-Tier (or Tomcat), it starts building views and
performing sync cache operations to ensure that the cache contents are up-to-
date. Loading those views in the cache takes time if there are a lot of AR System
server views in the viewstats.dat statistics file, which subsequently delays the
sync cache operation. During this period, if mid tier gets any request, it sends the
older version of the requested data.
As an administrator, you can check the sync status on the Cache Settings page
to verify whether the sync was completed successfully.
Definition Change Check Interval — This mid tier cache setting is configured to set an
interval (in seconds) at which information in the cache is updated. The default value is 3600
seconds. For details about the Definition Change Check Interval setting, see Cache
settings (see page 441).
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:
<?xml version="1.0" encoding="UTF-8"?>

<midtier-prefetch-config xmlns="http://www.bmc.com/remedy/midtier/midtier">
</midtier-prefetch-config>
On the Cache Settings page, ensure that the Perform Check check box is selected. This
activates another new 7.5.00 patch 004 feature called Sync Cache. Sync Cache eliminates
the need for administrators to flush the entire Mid-Tier cache after a form, active link, menu,
etc. definition change on the AR System server. Mid-Tier now automatically synchronizes its
cache for just the changed objects. It performs this check at the interval selected in the
Definition Change Check Interval field. Or, an administrator can press the new Sync
Cache button to have the changes synchronized immediately. The Sync Cache operation,
whether done automatically via Perform Check interval or by pressing the Sync Cache
button for the AR System server, synchronizes any of the following objects whose last
changed timestamp is newer on the AR System server than in the current mid tier cache:
Forms, Active Links, Containers (such as Guides, Applications, Web services, etc.), and
Menus (Character menus). Sync Cache completely removes and rebuilds the following
cache items since the performance hit is minimal: Group data, Role data, and Image
objects.
On the ARServer Settings page in the Mid Tier Configuration tool, enable the new feature,
Preload, by selecting the check box next to the server name. Preload will, on a restart of mid
tier, load all Active Links and Menus to the disk cache and any form which is user facing,
that is, any form which has an Active Link associated with it.
Select the Enable Cache Persistence check box.

Save changes to the Cache Settings.
Shutdown the JSP engine. Remove the contents of mid tier's /cache and /cachetemp
directories and start the JSP engine.
Allow Preload to complete processing.

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 (see page 442)). 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? (see page 384)

Updating browser cache (see page 386)
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 (see page 385).
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 (see page 385).
Example
/arsys/forms/*

Modifying the cache expiry settings

As an administrator, you can adjust the cache expiry settings from the config.properties file
located at /midTierInstallDir/WEB-INF/classes/. The browser uses these settings to determine
how long the content is cached.
Resources — The default setting for this request type is 86400 seconds (1 day). To change
the cache expiry settings for this request type, modify the following entry:
arsystem.resource_expiry_interval=86400
Form HTML / Javascript — The default setting for this request type is 3600 seconds (1
hour). To change the cache expiry settings for this request type, modify the following entry:
arsystem.formhtmljs_expiry_interval=3600
Updating browser cache

When a BMC Remedy AR System service pack, patch, or hotfix is applied to the BMC Remedy
Mid Tier binaries, or when changes are made to the BMC Remedy AR System definition files, you
must manually flush the browser cache.
Notes
You need not manually flush the browser cache whenever there is a change in
forms and other metadata in the AR System server. The changed forms are
automatically fetched from the mid tier and are reloaded in your browser.
If you have a server group setup with a load balancer, the browser cache
approximately takes 10 minutes to update and reflect the changes. You must sync
the cache after the shared database is updated with the changes.
Whenever there are changes in the AR System server, to keep the mid tier cache
up-to-date, you must still do a sync cache or flush cache.
In a Mid Tier cluster environment, to maintain consistency across all users, make
sure that the sync cache or flush cache operation is successfully completed
across all mid tiers.
If the browser cache is not up-to-date, you might get some JavaScript errors. For information about
these errors and the importance of updating the browser cache, see Knowledge Base article ID
KA310492.
To flush the cache, you need to delete the temporary internet files.
Note

You do not need to delete the cookies, form data, saved passwords, or browsing history.
For a list of compatible web browsers, see Compatibility matrix in the BMC Remedy ITSM
Deployment online documentation.
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:
Activating Perform Check (see page 387)

Activating Pre-Load (see page 388)
Enabling Cache Persistence (see page 389)
Clearing the cache and restarting the server (see page 390)
Using the mid tier with third-party load balancers (see page 390)
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 Sync in cluster check box is selected.
This activates Sync Cache.

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 usage history data
Note
The preload process starts after a 10 second delay.
1. Open the Mid Tier Configuration Tool and click AR Server Settings.
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.
4. Click Save.
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 (see page ).
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
Actions in ITSM 7.0.00 applications that trigger caching

In large BMC Remedy AR System applications such as those in the BMC Remedy IT Service
Management Suite (BMC Remedy ITSM Suite), some actions performed through the BMC
Remedy AR System Administration Console might trigger a client cache load or an admin copy
cache. The following table lists ITSM actions that can trigger a client re-cache or an admin copy
cache event.
Action Client cache Admin copy

load cache
Creating, modifying, or deleting a non-support user NO NO
Creating, modifying, or deleting an organization NO NO
Creating, modifying, or deleting a company NO YES 1
Creating, modifying, or deleting an association between a company and one of these NO NO

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

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:
Configuring BMC Remedy Mid Tier as a shared service (see page 393)
Onboarding a new tenant (see page 417)
Offboarding a tenant (see page 422)
Configuring the mid tier through a firewall (see page 424)
Configuring mid tier memory (see page 426)
Accessing the Mid Tier Configuration Tool (see page 427)
Configuring the Change Password page (see page 429)
Configuring the Overview page (see page 429)
Configuring the General Settings page (see page 431)
Setting pagination properties (see page 434)
Configuring the AR Server Settings page (see page 436)
Configuring the Cache Settings page (see page 440)
Configuring the Report Settings page (see page 459)
Configuring the Web Service Settings page (see page 461)
Configuring the Connection Settings page (see page 462)
Configuring a mid tier to launch a browser in a different mid tier (see page 465)
Cookies used by BMC Remedy Mid Tier (see page 467)
Settings in the config.properties file (see page 468)
Setting up a cluster with multiple tenants (see page 487)
Configuring BMC Remedy Mid Tier as a shared service

This topic provides the configuration steps for BMC Remedy Mid Tier as a shared service so that
the multitenant mid tier can serve requests from multiple customers.
Note
Before you perform the configuration steps for BMC Remedy Mid Tier as a shared
service:
Set up the enterprise centralized configuration server or servers.

Create a BMC Remedy Mid Tier cluster.
Install tenants or upgrade the platform components for the existing tenants.

To configure the mid tier as a shared service

Step Action Additional information
1 Add the first tenant to Onboard a new tenant on a BMC Remedy Mid Tier in the cluster. Configure the ECCS and
the cluster by provide the Cluster Identifier, add the tenant AR server and edit the tenant specific properties for
onboarding a new the BMC Remedy Mid Tier . For all other BMC Remedy Mid Tiers in the cluster, only configure
tenant on a BMC the ECCS and provide the Cluster Identifier that is the same as for the first BMC Remedy Mid
Remedy Mid Tier Tier. The Cluster Identifier for the cluster should be unique.
(see page 417)
2 Create a good cache A copy of the cache is used to restore the cache if it gets corrupted.
and back up the Mid
Tier cache (see page
455)
3 (Optional) Perform this step if you have installed BMC Atrium Single Sign-On as a High Availability (HA)
cluster environment for multitenancy support.
Configure BMC
Atrium Single Sign-
On for tenant
4 Configure BMC Perform the BMC Service Management Process Model (SMPM) configuration procedures.
Service Management
Process Model for a
tenant (see page 416)
5 Configuring the load Configure the load balancer to ensure that the user requests for the new tenant are diverted to
balancer (see page this cluster. Test the cluster and provide access to the new tenant.
489)
6 Add the remaining Add the remaining tenants to the cluster one by one by following steps 4 through 8.
tenants
7 (Optional) Add (n+1) If required, add an extra BMC Remedy Mid Tier to the cluster.
th BMC Remedy Mid
Tier to the cluster
8 (Optional) If a tenant needs to be moved from a cluster or is unsubscribed from the environment, offboard
Offboarding a tenant the tenant.
on a BMC Remedy
Mid Tier cluster (see
page 422)
9 (Optional) Set up If required, configure the tenant server to work with the chat server.
Openfire chat server
Related topics
Guidelines for BMC Remedy deployment architect

Glossary


To ensure seamless failover and fast response time in the BMC Remedy environment, the
deployment architect performs the following actions:
Lays down the deployment strategy and provides instructions to the BMC Remedy
administrator to implement the deployment strategy. See the following figure for a sample
deployment strategy.
Note
This diagram is only representative and does not indicate the actual number of
tenants or mid tiers in any cluster.
Decides how many clusters to create to support the existing Remedy customers based on
the benchmarking done for the RoD environment
Decides which mid tiers to include in the cluster based on the following guidelines:
Each computer hosting a mid tier must have the same hardware capacity (for
example, four CPUs at 2.0 GHz with 8 GB RAM and a 120-GB hard disk drive.
Each computer must have only one Tomcat instance and only one mid tier installed
within Tomcat.
If there are different subdomains or isolated networks, all computers in a cluster must
be a part of the same subdomain or isolated network to ensure optimal performance.
Decides which tenants must be added to the same mid tier in a cluster based on the
following guidelines:
The total number of concurrent users across all tenants added to a given mid tier
cluster must be less than or equal to 2,500.

For a symmetric configuration with three backups, a single mid tier instance does not
scale beyond 800 concurrent users. Remember these numbers while adding a tenant
to a given mid tier.
To take full advantage of cache objects comparison and sharing, all tenants in a
single mid tier must have the same number of languages. For example, if all tenants
in a mid tier have views only in English in all BMC Remedy IT Service Management
and BMC Service Request Management forms, maximum sharing of cache objects
across the tenants is achieved.
Combine all the tenants that have the same version. For example, add all tenants
that have BMC Remedy AR System 7604 SP2 to a single mid tier cluster.
Combine all tenants that have minimum customizations.
Decides the rules for the load balancer that are in line with the deployment strategy. For
example, sticky session should always be used, but routing the requests to the appropriate
clusters or mid tier must be based on which tenant is supported by which mid tier. Such
rules must be defined when a decision on the final cluster and tenant deployment is made.
Defines the necessary rule changes for the n+1 scenario (that is, while temporarily adding a
mid tier to or removing one from a cluster)
Identifies which mid tiers to add to a cluster
Assigns a unique cluster ID for each mid tier added to a cluster
Designates an AR System server as the Centralized Configuration Server (CCS)
Decides whether a dedicated cluster is required for a large Tier-1 tenant. Typically, tenants
should not be used across clusters. A large tenant (Tier-1) can use a dedicated cluster for
service.
Related topics
About Cluster ID (see page 415)

Tomcat cluster architecture (see page 397)
Configuring a cluster (see page 398)
Centralized configuration for the mid tier (see page 406)
f5 load balancer sample configuration (see page 508)
Guidelines for the BMC Remedy Administrator

As a BMC Remedy Administrator, follow these guidelines to ensure smooth functioning and
maintenance of the Remedy OnDemand environment:
Install and upgrade BMC Remedy Mid Tier to the latest version.
Install BMC Atrium Single Sign-On.
Based on the deployment strategy, configure a Tomcat cluster.
Install and configure Centralized Configuration server. For information, see Centralized
configuration (see page 396) and Centralized configuration for mid tier (see page 396).
Decide on and adhere to a naming convention for cluster IDs.
Onboard a tenant.

Add a tenant.
Configure tenant-specific properties.
Preload the cache.
Configure a load balancer.
Shut down the mid tier and back up the good copy of the cache. For information, see
Backing up mid tier cache (see page 396).
Keep the setup ready to deploy an additional mid tier to the cluster on the fly. For
information, see Adding an extra mid tier to a cluster (see page 396).
Enable the tenant console from the web.xml file. For information, see Enabling and
disabling multi-tenancy support.
Add a realm for the tenant to access the Tenant Console. For information, see Adding or
deleting realms for multi-tenancy support.
Add users to the BMCSaaSAdmin group for providing tenant administrator privileges. For
information, see Managing the Tenant Console.
Tomcat cluster architecture

For the Tomcat cluster, you configure two nodes as part of one cluster. Deploy each node on a
separate virtual machine and install one mid tier on each node. Use the symmetric configuration in
which both mid tiers use the same AR System server, both use preloaded cache, and both have
the exact copies of the cache after preload. Configure the load balancer to send requests of any
client to any of the mid tiers and ensure that the sticky session behavior is set to ON.
For more information about configuring a Tomcat cluster, see Configuring a cluster (see page 398).
When a user logs on to a node, in-memory session replication happens in real time.
The following diagram shows that Request 1 with Session X and Request 2 with Session Y are
handled by the load balancer. Assume that Request 1 is served by Node 1 and Request 2 is
served by Node 2. Even so, both nodes will have information about both the sessions, that is,
Session X and Session Y are part of session replication. Either node can pick up the other session
seamlessly if the other node crashes. A user does not have to log on again even if the serving
node is down. This session is picked up immediately by the second node.

Related topic
Guidelines for BMC Remedy deployment architect (see page 395)
Configuring a cluster
Notes
BMC recommends you to configure a BMC Remedy Mid Tier cluster using Tomcat.
BMC does not supports the clustering for webservers other than Tomcat.
BMC Remedy AR System installer allows you to only install or upgrade the BMC
Remedy Mid Tier and does not provides an option for Tomcat clustering.
You should setup the cluster manually, following the steps provided in this topic.
See the Compatibility matrix in the BMC Remedy ITSM Deployment online
documentation for supported version of Tomcat.
Ensure seamless failover by configuring the mid tier on an Apache Tomcat cluster (see page 397)
. To add the mid tier in a Tomcat cluster, install mid tiers on different virtual computers and
configure the cluster with the following procedure.
1. Stop Tomcat.
2. Open the arsys.xml file located in the TomcatInstallationFolder\conf\Catalina\localhost
folder in a text editor, and replace the <Manager> tag with the following XML:

2.
<Manager className= "org.apache.catalina.ha.session.DeltaManager"

expireSessionsOnShutdown= "false"
notifyListenersOnReplication= "true" />
3. Open the server.xml file located in the TomcatInstallationFolder\conf folder in a text

editor and make the following changes:
Locate the <Engine> tag and add the jvmRoute attribute.
Use Node1 for the first node, Node2 for the second, and so on.
<Engine name="Catalina" defaultHost="localhost" jvmRoute="
Node1">
Copy the <Cluster> tag information from the attached file and paste it after the
<Engine> tag in your server.xml file. You can download the sample server.xml file.
<Cluster className= "org.apache.catalina.ha.tcp.SimpleTcpCluster"

channelSendOptions= "8" >
<Manager className= "org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown= "false"
notifyListenersOnReplication= "true" />
<Channel className= "org.apache.catalina.tribes.group.GroupChannel" >
<Membership className="org.apache.catalina.tribes.
membership.McastService"
address= "<ipAddress>"
port= "45570"
frequency= "500"
dropTime= "3000" />
<Receiver className="org.apache.catalina.tribes.transport.
nio.NioReceiver"
address= "auto"
port= "4000"
autoBind= "100"
selectorTimeout= "5000"
maxThreads= "6" />
<Sender className="org.apache.catalina.tribes.transport.
ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.
nio.PooledParallelSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.
interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.
interceptors.MessageDispatch15Interceptor"/>
</Channel>
<Valve className= "org.apache.catalina.ha.tcp.ReplicationValve"
filter= ".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.
*\.txt|.*\.jsp|.*\.swf|.*BackChannel/*|.*./resources/.*|.*.
/sharedresources/.*|.*./plugins/.*|.*./pluginsignal/.*|.*./imagepool/.*"
statistics= "false" />
<Valve className= "org.apache.catalina.ha.session.JvmRouteBinderValve" />
<Deployer className= "org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir= "/tmp/war-temp/"

deployDir= "/tmp/war-deploy/"
watchDir= "/tmp/war-listen/"
watchEnabled= "false" />
<ClusterListener className="org.apache.catalina.ha.session.
JvmRouteSessionIDBinderListener"/>
<ClusterListener className="org.apache.catalina.ha.session.
ClusterSessionListener"/>
</Cluster>
Note
The default value for the <ipAddress> variable is 228.0.0.4. This IP

address and port number defines a unique cluster. However, for each
member of a cluster, ensure that they have the same multicast IP address
and port number.
4. Enter the multicast IP address of the host on which you want the session replication to take
place in the Address value instead of auto. For example, in the <Receiver> tag, modify
address="auto" to address="172.x.x.x". For more information, see FAQ about
cluster configuration (see page 403).
5. (Optional) Add two new file handlers 5cluster.org.apache.juli.FileHandler and 6cluster.
org.apache.juli.FileHandler in the handlers section to the logging.properties file.
handlers = 1catalina.org.apache.juli.FileHandler, \
2localhost.org.apache.juli.FileHandler, \
3manager.org.apache.juli.FileHandler, \
5cluster.org.apache.juli.FileHandler, \
6cluster.org.apache.juli.FileHandler, \
java.util.logging.ConsoleHandler
6. (Optional) To increase the cluster logging, change the log level to FINE for the following file
handlers in the logging.properties file located in the TomcatInstallationFolder/conf folder:
5cluster.org.apache.juli.FileHandler and 6cluster.org.apache.juli.FileHandler.
5cluster.org.apache.juli.FileHandler.level = INFO
5cluster.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
5cluster.org.apache.juli.FileHandler.prefix = cluster.
6cluster.org.apache.juli.FileHandler.prefix = ha.
org.apache.catalina.tribes.MESSAGES.level = INFO
org.apache.catalina.tribes.MESSAGES.handlers = 5cluster.org.apache.juli.
FileHandler

org.apache.catalina.tribes.level = INFO
org.apache.catalina.tribes.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.ha.level = INFO
org.apache.catalina.ha.handlers = 6cluster.org.apache.juli.FileHandler
7. Restart Tomcat.
8. Verify whether the node is added to the cluster:
a. Open the ha.date.log file located at /opt/apache/tomcat7.0/logs for Linux and <C:
\Program Files\Apache Software Foundation\Tomcat7.0\logs> for Windows.
b. Search for memberAdded entry. If you have added four mid tiers to the cluster, you
should see three memberAdded entries and their IP addresses in the file for the other
three members. Ensure that the IP address does not represent a localhost.
Note
To add an extra mid tier to the cluster (see page 405), perform the same configurations
on the extra (n+1) mid tier.
To access the mid tier configuration URL, BMC recommends that you use the HTTP URL in the
following format:
http://mtMachineName:8080/arsys/shared/config/config.jsp
Recommendations
BMC recommends that to improve application scalability, increase the File Descriptor limit in mid
tiers running in a cluster. If you have a cluster of two mid tiers with 12 tenants, which is serving
3600 users, set the File Descriptor limit to 35,000 .
Note
Average load per tenant is considered as 300 users.
To set the File Descriptor limit, perform the following steps:
Edit the /etc/security/limits.conf file and add the following:
root soft nofile 35000
Edit the /etc/bashrc file and set the unlimit value as follows:

if [ "$EUID" = "0" ]; then
ulimit -n 35000
fi
Edit the /etc/sysctl.conf file and increase the File Descriptor limit for the system as follows:
fs.file-max = 210000
Note
Ensure that you set the system-wide limit of File Descriptors to approximately 6 times of
the per process limit set in the limits.conf file.
Refer to the following table for guidance on deciding the File Descriptor limit:
S Component Variable Description

No
1 Tomcat maxThreads setting in Tomcat HTTP maxThreads defines the maximum connections used by
connections Connector Tomcat when
BIO Connector is used.
2 Tomcat NIO Default setting is 6 NIO Receivers for Session Replications.

Receivers
3 Tomcat and Mid Estimate is 1200 Class loader for JAR files loaded by Tomcat. This includes
Tier Class JARs in Mid Tier distribution, configured Third-party JARs,
Loaders and DVF plug-ins.
4 Mid Tier 1 + 1 * Number of Tenants 1 for global configuration and 1 per tenant
properties files
5 Mid Tier Cache 27 x 2 = 54 27 categories x 2 files per category. Data files are always
files open.
Index files are read into Memory at startup and closed and
later written to
during Mid Tier shutdown.
6 Mid Tier Cache 1 Single file for Cache lock status

lock file
7 Java API RPC arsystem. Configured by arsystem.

connections to pooling_max_connections_per_server pooling_max_connections_per_server setting
AR Server from Mid Tier Configuration * Number of in Mid Tier Configuration
Tenants
8 Java API JMS 1 + 1 * Number of Tenants 1 for ECCS and 1 per Tenant
Connections for
CCS
9 Attachments Estimate is 20% * Maximum Concurrent Attachment files and report files created by MT on Disk
and Reports Users on the Mid-Tier Node

S Component Variable Description

No
10 SSO Agent - 1 A single Configuration file is used by the SSO Agent which
Files is queried from the SSO Server
11 SSO Agent – maxThreads setting in Tomcat HTTP SSO Agent opens a URLConnection to SSO Server when
Connections to Connector it logs in a
SSO Server User or validates SSO Token with SSO Server
12 Safety Factor 25% * Sum of (#1 to #11)
Total Sum of #1 to #12 rounded up to nearest 5000 on 6th

higher side
Related topics
FAQs about cluster configuration (see page 403)

Enabling logging (see page 413)
FAQ about cluster configuration

This topic provides answers to frequently asked questions about Tomcat cluster configuration.
How do I configure a Tomcat cluster if I have multiple network interfaces?
You have the following options:
Edit the server.xml file located in the TomcatInstallationFolder\conf folder and in the
Receiver tag, for the address value, instead of auto, enter the IP address of the network
interface card to which you want the session replication to take place.
For example, if you have two network interface cards, eth1 with 10.x.x.x as the IP address and
eth2 with 172.x.x.x as the IP address, and if you want the session replication to happen on eth2,
you must set the address value to 172.x.x.x.
Original address value in the Receiver tag:
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="4000"
autoBind="100"
selectorTimeout="5000"
maxThreads="6"/>
New address value in the Receiver tag:

address="172.x.x.x"
port="4000"
autoBind="100"
maxThreads="6"/>
For information about clustering and session replication, see the Apache Tomcat documentation at
http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html.
Disable the network interface that you do not intend to use. For example, if you want to
disable eth1, use any one of the following commands at the command prompt:
ifconfig eth1 down
ifdown eth1
Note
Verify your etc/hosts file. Remove any bad entries that are present.
I see the IP address of the local host against the memberAdded entry in the cluster log. What do I
do?
Edit the server.xml file located in the TomcatInstallationFolder\conf folder and in the
Receiver tag, for the address value, instead of auto, enter the IP address of the host to
which you want the session replication to take place.
Original address value in the Receiver tag:
address="auto"
port="4000"
autoBind="100"
maxThreads="6"/>
New address value in the Receiver tag:
address="172.x.x.x"
port="4000"
autoBind="100"

maxThreads="6"/>
For information about clustering and session replication, see the Apache Tomcat documentation at
http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html.
Adding an extra mid tier to a cluster

When an increase in demand requires extra capacity in a cluster, you can add an extra mid tier to
the cluster. The newly added mid tier must seamlessly start serving requests and share the load
along with other mid tiers in the cluster. Suppose that you have four mid tiers and eight AR System
servers operating in a cluster, serving requests from 2,400 users. If you find that each mid tier is
serving more than 75 percent of its capacity and you expect the load to further increase, you can
add a fifth mid tier and distribute the load equally among all the mid tiers.
Note
This procedure also applies when a mid tier in a cluster goes down and the BMC Remedy
AR System administrator brings it up.
Before you begin (see page 405)

To add the extra (n+1) mid tier (see page )
Before you begin
Plan your deployment strategy. For example, you might have to decide whether to deploy
n+1 or n+2 mid tiers to the cluster.
Ensure that you have a separate computer. If you are deploying n+2 mid tiers, ensure that
you have two computers available.
Ensure that the computers have the same configuration as that of other mid tiers in the
cluster in terms of memory, CPU usage, disk space, and so on.
Ensure that the computers have the same cluster configuration (see page 398).
Notes
Ensure that the extra mid tier is already set up in the cluster but is not running, and
that you have deleted the midTierInstallationDirectory/cache folder before
starting the mid tier.
To avoid the extra time required to copy the cache folder, ensure that you already have a
"good copy" of the preloaded cache in the n+1 mid tier (for example, in the /opt
/Preload_Cache folder). Ensure that you store the good copy of the cache on a local drive
and not on a shared drive, which can delay copying the cache folder.

Add the cache directory path to the arsystem.ehcache.midTierBackupCacheDir

property in the config.properties file of the n+1 mid tier. For example:
arsystem.ehcache.midTierBackupCacheDir = /opt/Preload_Cache
Note
If you are using a Centralized Configuration Server (CCS), ensure that this
property (Cache Backup Directory) is set correctly from the Cache Settings page
from any of the mid tiers in the cluster. Ensure the availability of the good copy of
the cache in this folder on all mid tiers. For more information, see Backing up the
mid tier cache (see page 456).
If you are using Centralized Configuration Server, copy the ccs.properties file in the
midTierInstallationDirectory/WEB-INF/classes folder from other mid tier.
To add the extra (n+1) mid tier
1. Start the n+1 mid tier:

a. Start the mid tier to connect to the CCS server by using ccs.properties and refresh
the local copy of config.properties. This action also copies the cache backup from
the backup directory and starts using it automatically.
b. After the n+1 mid tier is started, verify the cache folder located in the
midTierInstallationDirectory/cache folder of the n+1 mid tier. The size of this cache
folder must be same as the good cache copy stored in the /opt/Preload_Cache
folder.
2. Ensure that the n+1 mid tier is added as a node to the appropriate f5 load balancer pool.
Otherwise, f5 does not balance the load across the n+1 mid tier.
3. Verify whether the newly added mid tier is serving requests by:
Looking at the status of the relevant node in f5 load balancer
Reviewing the number of views generated in the Cache Advanced page of the newly
added mid tier (For example: http://localhost:portnumber/arsys/shared/config
/config_cache_adv.jsp)
The newly added mid tier can now handle all requests seamlessly without causing delays and
performance issues.
Centralized configuration for the mid tier

Centralized configuration refers to storing configuration form data at a common location that can be
accessed by other computers. Centralized configuration simplifies the management of
configuration data and the sharing of configuration settings across servers. For more information,
see Centralized configuration (see page 1144).

You must configure a BMC Remedy AR System server to act as a Centralized Configuration
Server (CCS). The Centralized Configuration Server is a BMC Remedy AR System server that
does not have any applications installed or any end-user interactions. Centralized Configuration
Server needs limited resources in terms of CPU and RAM.
The Centralized Configuration Server ensures consistency by communicating changes to the

global properties across all the mid tiers in a cluster. If a configuration server is defined while
adding a tenant, that tenant configuration server maintains a copy of the tenant-specific settings.
When a tenant-specific property is modified on one mid tier, the Tenant Configuration Server
automatically sends the notification to other mid tiers that have the same tenant added, so that
these configuration changes are also synchronized by each mid tier in the same cluster.
For example, you have 10 mid tiers in a cluster. Before centralized configuration, each tenant was
managed independently. To change a configuration setting, you had to make the same change for
each tenant in the cluster. With centralized configuration, because all settings are stored in forms,
you can change the settings for multiple tenants in a cluster at one time. Centralized configuration
enables you to share configuration settings across all tenants in a cluster.
Note
If you are using a version of BMC Remedy AR System server earlier than 20.14.01 and
cannot set Centralized Configuration Server and Tenant Configuration Server, you must
manually update the global and tenant-specific settings for all the mid tiers in the cluster.

Use the Mid Tier Configuration Tool to update the settings. If you do not have access to
the Mid Tier Configuration Tool, edit the config.properties and tenants/config_
tenantName.properties files.
To set the Centralized Configuration Server properties
1. Open the BMC Remedy Mid Tier Configuration Tool from the URL: http://hostname:port
/arsys/shared/config/config.jsp.
2. Click Central Config Settings.
3. In the Central Config Settings page, enter the following information:
a. In Server Name, enter the name of the AR System server that is the designated as
the Centralized Configuration Server in the cluster.
b. In Cluster ID, enter the unique cluster ID (see page 415) of the cluster to which the
mid tier belongs.
c. Enter the administrator password.
d. (Optional) Enter the port number and RPC number.
4. Click Save.
Note
You can configure a BMC Remedy AR System server as a Centralized

Configuration Server or a Tenant Configuration Server only if the AR System
server version supports centralized configuration and has the configuration-related
system forms and notification capability.
5. Click Publish to create or update global properties from the config.properties file to
Centralized Configuration Server.
Note
After you publish, properties that are deleted from the config.properties file are
not deleted from the Centralized Configuration Server. However, deleted
properties are reflected in the current mid tier memory immediately and are
restored when the mid tier is restarted. Click Restore to restore global settings
from the Centralized Configuration Server to the config.properties file. Exercise
caution when deleting any property directly from the Centralized Configuration
Server forms.
6. Click Restore to update the global settings from Centralized Configuration Server to the
config.properties file.

Note
The properties that are not available for editing through the Centralized Configuration
Settings page must be edited directly in the config.properties file.
A ccs.properties file is added to the midTierInstallationDirectory\WEB-INF\classes folder and

contains the following information:
arsystem.cluster.id
The cluster identifier of the mid tier cluster. All mid tier instances in the same cluster share
the cluster identifier.
arsystem.ccs.password
The encrypted mid tier service password for the Centralized Configuration Server.
arsystem.ccs.host
The name of the Centralized Configuration Server.
arsystem.ccs.port
The port number of the Centralized Configuration Server.
The mid tier uses the ccs.properties file for connecting to the Centralized Configuration Server on
startup and for updating its configuration files for global settings (config.properties) and tenant-
specific settings (config.tenantName.properties).
Note
If you have configured a valid Centralized Configuration Server or Tenant Configuration

Server, refrain from making any changes directly to the properties files. These changes
might be overwritten during the next mid tier restart. Make all the necessary changes in
the BMC Remedy AR System Configuration Component Setting form on the Centralized
Configuration Server or Tenant Configuration Server, using the appropriate cluster ID or
tenant name. The changes will take effect in all concerned mid tier instances and
corresponding properties files by means of a periodic notification (typically after 30
seconds). However, changes to some of the properties, such as Ehcache settings and
number of threads, require the mid tier to be restarted. For more information, see
Centralized configuration (see page 1144).
Configuring the mid tier for multitenancy

To configure the mid tier for multitenancy, first add tenants to the mid tier and then configure the
tenant-specific properties. The following topics are provided:
To add a tenant (see page 410)

To edit tenant-specific properties (see page 411)

To delete a tenant (see page 412)

Mapping a tenant to multiple AR System servers (see page 412)
Configuring global settings for all tenants (see page 413)
Identifying whether the mid tier is in multitenant mode (see page 413)
To add a tenant
1. Open the BMC Remedy Mid Tier Configuration Tool from the URL http://hostname:
portnumber/arsys/shared/config/config.jsp
2. Click the Tenant Settings link.
3. On the Tenant Settings page, click Add Tenant.
4. In the Add New Tenant page, enter the following information.

a. In the Tenant Name field, enter the name of the tenant (for example, Tenant1).
b. In the Virtual Host Name field, enter the virtual name of the host (for example,
Tenant1.bmc.com).
Note
You must map this virtual host name with the pool name in the f5 load
balancer. For more information, see f5 rules (see page ).
c. In the Web Reports Base URL field, enter the base URL (for example,
https://Tenant1.onbmc.com:8080/).
d. (Optional) From the Tenant Configuration Server list, select an AR System server
as your configuration server.
This list is populated based on the AR System servers that are added to the mid tier.
For more information, see Adding or deleting a server (see page 438).
e.
e. (Optional) Click Browse to specify the location of the config.properties file.

By default, the existing config.properties file is located in the
midTierInstallationDirectory\WEB-INF\classes folder.
f. (Optional) Clear the Also add to tenant's server list check box.
The configuration server is not added as a server to the tenant. By default, this check
box is selected.
5. Click Save.
Note
Ensure that the virtual host is accessible to the users by making appropriate changes in
DNS or load balancer settings.
The tenant is added to the mid tier. Each tenant that is added to the mid tier has a corresponding
tenant-specific property file. For example, if you add a tenant named Tenant1, a properties file
called config.Tenant1.properties is added to the midTierInstallationDirectory\WEB-
INF\classes\tenants\ folder.
Note
If you add a tenant with the name of a tenant that was deleted or offboarded from any mid
tier previously, a warning message is displayed. When you delete a tenant, the tenant is
deleted but the tenant configuration is not deleted from the Centralized Configuration
forms. For more information, see Centralized configuration for the mid tier (see page 406)
.
To edit tenant-specific properties
1. On the Tenant Settings page, select a tenant that you want to edit and click Edit.

2. On the Edit Tenant page, edit the tenant-specific properties that you want to change for this
tenant.
3. Click Save Tenant.
To delete a tenant
1. Open the BMC Remedy Mid Tier Configuration Tool from the http://hostname:portnumber
/arsys/shared/config/config.jsp URL.
2. Click the Tenant Settings link.
3. From the Tenant Settings page, select the check boxes in the Delete/Edit column for one or
more tenants.
4. Click Delete.
Note
Use caution when deleting a tenant. Ensure that the users who are logged on using the
tenant's virtual URL stop accessing the mid tier; otherwise they might see unexpected
behavior.
Mapping a tenant to multiple AR System servers

You can add multiple AR System servers to a tenant; however, only one AR System server will be
the primary server used for authenticating, setting preferences, the home page, and the data
visualization module. For more information, see Adding or deleting a server (see page 438).

Note
A single AR System server cannot be mapped to more than one tenant.
Configuring global settings for all tenants

You can configure global configuration settings for tenants such as the cache settings, report
settings, and log settings. For more information, see Configuring Mid Tier (see page 393).
Identifying whether the mid tier is in multitenant mode

When you access mid tier using the virtual host name, the mid tier is in the multitenant mode. For
example, if your URL starts with http://Tenant1.onbmc.com/arsys/forms/, you are using a mid tier
that is in multitenant mode. If your URL starts with http://hostName/arsys/forms/, you are
accessing a mid tier that is not in the multitenant mode.
For a mid tier to be accessed in multitenant mode, ensure that at least one tenant with a virtual
host name is added to the mid tier.
Note
The Mid Tier Configuration Tool is accessed only by the BMC Remedy AR System
administrator using the actual mid tier host name rather than the virtual host name.
Enabling logging
To debug issues with session replication or to verify whether failover is taking place in the Tomcat
cluster, you must edit the logging.properties file located in the TomcatInstallationFolder/conf
directory.
Note
The logging.properties file is available as an attachment to this topic.
Edit the attached logging.properties file to add new file handlers and set the debug log level to
Info. For example, create two new file handlers: 5cluster.org.apache.juli.FileHandler and
6cluster.org.apache.juli.FileHandler, as shown in the following code. Add the code to the
logging.properties file.
5cluster.org.apache.juli.FileHandler.prefix = cluster.

6cluster.org.apache.juli.FileHandler.prefix = ha.
org.apache.catalina.tribes.MESSAGES.level = INFO
org.apache.catalina.tribes.MESSAGES.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.tribes.level = INFO
org.apache.catalina.tribes.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.ha.level = INFO
org.apache.catalina.ha.handlers = 6cluster.org.apache.juli.FileHandler
Note
When you install Tomcat through the latest version of BMC Remedy AR System, the
cluster log settings are already added by the installer. However, you can change the log
level whenever required.
Glossary
load balancer
A transparent network device that distributes the traffic from multiple tenants to several tenant AR
System servers, preventing BMC Remedy AR System servers from becoming overloaded.
Distributing workload among several BMC Remedy AR System servers leads to performance
benefits and cost savings.
Mid Tier cluster

A group of Tomcat servers with the mid tier application running on them. The cluster acts as a
single system and provides high-availability, failover, and load balancing capabilities.
multitenancy
Refers to the ability of a single instance of an application running on a server to serve multiple
customers. Customers, in this case, are called the tenants. In the multitenant environment, each
tenant is given the provision to customize the application according to their requirements.
server group
Multiple servers that are connected to each other and operate together; they share the work load
and also balance the load. One server in the server group is usually designated as the primary
server, which performs administrative activities and others are designated as secondary servers.

shared service
The consolidation of business operations that are used by multiple parts of the same organization.
tenant
A customer subscribing to the services provided in the SAAS model.
About Cluster ID
A cluster ID is a unique identification given to a cluster operating in the RoD environmen t. All mid
tiers within a cluster share a unique cluster ID. When you configure the Centralized Configuration
Server settings for each mid tier, ensure that the mid tiers within a cluster are configured with the
same cluster ID. Having a cluster identified by a unique cluster ID is essential because Centralized
Configuration Server can notify changes to the global properties across all the mid tiers within a
cluster. For more information about configuring the cluster ID for each mid tier, see Centralized
configuration for the mid tier.
You must decide a unique cluster ID for each cluster. For example, for Cluster1, you can add
Cluster1 as the cluster ID, for Cluster2, add Cluster2, and so on.
The following diagram illustrates the use of a cluster ID.

Related topics
Configuring a cluster
Configuring SMPM for a tenant

To configure BMC Service Management Process Model (SMPM) for a tenant, perform the following
steps:
1. Log on to the tenant.

2. Navigate to the Integration Configuration form.
3. Open the SYS:Integration Management form or perform the following steps:
Select Application Flyout > Administrator Console > Application Administrator
Console.
On the Application Administration Console page, select Custom Configuration
tab.
Navigate to Foundation > Advanced Option > System Configuration Settings >
Integration Management and click Open.
4. Perform a search to list all the records (for example: Integration Application = %).
5. For the following records, update the entry with the following details and then save each
entry.
Host = /
Port = “” (Empty)
Status = Enabled

Onboarding a new tenant

This topic explains how to onboard a new tenant in your existing multitenant mid
tier setup.

To onboard a tenant on the first mid tier in the cluster (see page 417) Configuring the mid tier for
To onboard a tenant on the other mid tiers in the cluster (see page 419) multitenancy (see page 409)
Before you begin

Ensure that you have n mid tiers that are:
Set up as a Tomcat cluster (see Configuring a cluster (see page 398))

Configured for SSO (see Configuring BMC Atrium SSO with mid tier deployed as a shared
service)
To onboard a tenant on the first mid tier in the cluster
1. Log on to BMC Remedy Mid Tier Configuration Tool:

If the mid tier is installed on the local computer using the default context path, enter
http://localHost/arsys/shared/config/config.jsp in your browser.
If the mid tier is not installed on the local computer, open a browser and enter the
URL in the following format:
http://hostName:portNumber/contextPath/shared/config/config.jsp
hostName is the name of the host computer for the mid tier.
portNumber is an optional port number; it is required if the web server is not
using the default port (port 80).

contextPath is the path to the location of the mid tier in the Oracle JSP engine (
arsys, by default).
2. When the Login page appears, enter the logon password for the Mid Tier Configuration Tool.
If you have not changed the password from the default, enter arsystem.
3. Click the Tenant Onboarding link.
4. (Optional) In the Centralized Configuration Server Settings page, shown in the following
figure, configure the Centralized Configuration Server settings.
For more information, see Centralized configuration for the mid tier (see page 406).
5. Click the Next step button or the Tenant AR Server tab.

The AR Server Settings page opens, as shown in the following figure:
6. Add and configure an AR System server (see page 438):

Ensure that the Pre-load check box is selected. If you do not select this check box,
the Preload button will not be available on the Cache Settings page.
Ensure that you enter the tenant virtual host name (for example, http://Tenant1.
onbmc.com/contextPath) in the Default Web Path and Email Notification Web Path
fields in the Advanced tab of the Server Information form. The values of these fields
are used in various BMC Remedy IT Service Management workflows; therefore, you
must enter the tenant-based URL in these fields so that customers receive the
correct URL. For information about the Default Web Path and Email Notification
Web Path fields, see Setting advanced security options using the Server Information
7. Click the Next step button or the Tenant Creation tab .
The Tenant Settings page opens, as shown in the following figure:

8. Add a new tenant (see page 409) with a name such as tenant1.
Ensure that the tenant name does not contain any special character.
9. (Optional) Select a tenant and click the Next Step button or the Tenant Configuration tab.
10. In the Edit Tenant page, make changes to tenant-specific properties (see page 409).
11. Click the Preload New Tenant tab.
The Cache Settings page opens.
12. Click Preload for the tenant AR System server.
(The Preload button is not available if you did not select the Pre-load check box in the AR
Server Settings page in step 6.)
You will see that initially the status of the preload is shown as Not Running.
Recommendation
BMC recommends that you perform preload when your system has a lesser load
and that you use the round-robin method to preload servers one at a time.
13. After the preload is completed, configure your load balancer to start sending requests to this
tenant using the virtual host name.
For example, the virtual host name of the tenant1 tenant can be http://tenant1.onbmc.com.
14. Verify whether the tenant is successfully added by logging on to the BMC Remedy IT
Service Management application, using the virtual host name of that tenant.
To onboard a tenant on the other mid tiers in the cluster

Perform the appropriate action:
If the Centralized Configuration Server is not configured, perform all the steps in To onboard
a tenant on the first mid tier in the cluster (see page 417).
If the Centralized Configuration Server is configured, review all the steps in To onboard a
tenant on the first mid tier in the cluster (see page 417) and make changes, if required.
However, you must explicitly preload the tenant AR System server. For information, see
Setting up a cluster with multiple tenants (see page 487).
Related topics

Configuring the mid tier for multitenancy (see page 409)

Setting up BMC Remedy Smart Reporting as a cluster and onboard tenant
1. To set up BMC Remedy Smart Reporting as a cluster (Tomcat only) perform the following
steps:
Note
Before you configure the cluster, ensure that all the severs in cluster are in same
time zone and are in sync. Also, ensure that BMC Remedy Smart Reporting is
installed on all the nodes pointing to primary node repository.
2. Perform one of the following:

If you are using a template, edit the JDBC URL in the <SmartReportingInstallDir>
/appserver/webapps/ROOT/WEB-INF/web.xml file to the reporting database host name.
<init-param>
<param-name>JDBCUrl<param-name><param-value>jdbc:jtds:sqlserver://<DB-
Server>:<Port>/SmartReporting;instance=/windows
</param-value>
</init-param>
Or
Install the BMC Remedy Smart Reporting on a node and copy the files to the secondary
servers.
3. On the web.xml file located at <SmartReportingInstallDir>/appserver/webapps/ROOT
/WEB-INF update the following:
a. Update and add the following:


<servlet>
<servlet-name>ClusterManagement</servlet-name>
<servlet-class>com.hof.mi.servlet.ClusterManagement</servlet-class>
<init-param>
<param-name>ClusterType</param-name>
<param-value>DYNAMIC</param-value>
</init-param>
<init-param>
<param-name>SerialiseWebserviceSessions</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>CheckSumRows</param-name>

</init-param>
<init-param>
<param-name>EncryptSessionId</param-name>
</init-param>
<init-param>
<param-name>EncryptSessionData</param-name>
</init-param>
<init-param>
<param-name>AutoTaskDelegation</param-name>
</init-param>
<load-on-startup>11</load-on-startup>
</servlet>
b. On the MIStartup Servlet block, update the following:
<init-param>
<param-name>DisableTaskScheduler</param-name>
<param-value>TRUE</param-value> </init-param>
Important
In a clustered environment, each Smart Reporting node is configured by-

default to run background tasks that also includes publishing reports. This
could result in sending the reports multiple times. Thus, it is recommended
that you enable the background tasks on only one node. You can do this by
changing the param-value to FALSE and save the web.xml file.
c. Comment the following :
<servlet>
<servlet-name>SystemTaskManager</servlet-name>
<servlet-class>com.hof.servlet.SystemTaskManager</servlet-class>
<load-on-startup>8</load-on-startup>
</servlet>
d. Add <distributable/> tag

Following is sample snippet
<web-app>
<distributable/> 
<plugin>
<name>ARSYS.ARDBC.PREVIEW</name>
/approval/bin/arasj90_build001.jar</pathelement>
<classname>com.bmc.arsys.approval.main.ApprovalPlugin</classname>


/arserver/api/lib/arcmnapp90_build001.jar</pathelement>
/arserver/api/lib/arutil90_build001.jar</pathelement>
</plugin>
<maskingImplementation>com.bmc.arsys.approval.signal.SignalMaskForASJ
</maskingImplementation>
b. Save and close the file.

5. Restart the BMC remedy AR System server for the changes to take effect.
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:
2. To start the Approval Server, remove the comment markers from the files discussed in steps
1a and 1b.

Configuring BMC Remedy Email Engine

This section explains how to create and configure BMC Remedy Email Engine mailboxes and how
to set security options. The following topics are covered:
Configuring outgoing mailboxes (see page 604)

Performance and configuration settings for Email Engine (see page 609)
BMC Remedy Email Engine mailboxes (see page 624)
Saving outgoing notifications in MAPI (see page 625)
Changing the default time interval (see page 625)
Testing your mailbox configuration (see page 626)
Configuring incoming mailboxes (see page 627)
Stopping and starting the Email Engine (see page 632)
Identifying the Email Engine component (see page 634)
Modifying the companionservername or RMIPort properties (see page 634)
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 (see page 1467).
The following topics provide detailed information about how to configure the basic and advanced
properties of outgoing mailboxes:
Configuring basic outgoing mailbox properties (see page 605)

Configuring advanced outgoing mailbox properties (see page 606)
Configuring basic outgoing mailbox properties

Outgoing mailboxes support the MAPI and SMTP mail protocols.
To create a basic configuration for your outgoing mailbox
1. Open the AR System Email Mailbox Configuration form.

2. Enter the following information in the fields above the tabs:
Mailbox Name — Enter a name that describes the function of the mailbox. For
example, enter ARSystemEmail - Outgoing.
Mailbox Function — Select Outgoing.
Status — Select Enabled.
3. In the Basic Configuration tab, select either SMTP or MAPI as the Email Server Type,
and set the following values in the remaining fields:
MAPI (for 32-bit JVM only):
Server Type — Select MAPI.
Polling Interval — Select a polling interval for the Email Engine to check for
new outgoing email from the BMC Remedy AR System server.
Profile Name — Enter the name of the Microsoft Exchange profile that you
created during the product installation.
This field is required because a profile is used to see the MAPI email account
configuration information. For more information about Microsoft Exchange
profiles, see your Microsoft Exchange documentation.
SMTP
only:
Server Type — Select SMTP.
new outgoing email from the BMC Remedy AR System server.

Email Server Requires SSL — Select Yes to enable Secure Sockets Layer
(SSL). For more information, see Configuring SSL for the Email Engine (see
page ).
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 (see page 1559).
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 (see page 1469).
Performance and configuration settings for Email Engine

The email engine internally uses most configuration settings with their default values. The
centralized configuration forms and the EmailDaemon.properties file let you specify values other
than the defaults for these settings.
For specific troubleshooting issues, see Troubleshooting Email Engine (see page 4661).
For information about the email engine properties in the centralized configuration forms, see
Configuration settings C-D (see page 1168).
Note
When you modify entries in the AR System Configuration Generic UI form, the changes
are effective in 30 seconds (the default value for the com.bmc.arsys.emaildaemon.
configurationcheckinterval setting). You can modify the value for this setting from the
EmailDaemon.properties (see page 612) file.
The following topics provide information about the various settings for Email Engine:
EmailDaemon.properties file (see page 609)

Settings in the EmailDaemon.properties file (see page 612)
Related topics

Configuration settings (see page 1147)
Updating configuration settings (see page 1235)
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 (see
page 612).
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.
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 (see page
4661) and its subtopics.
Note
BMC recommends that you use the AR System Configuration Generic UI form
to modify the centralized configuration settings. Do not use the EmailDaemon.
properties file to modify the configuration settings on the AR System
Configuration Generic UI form. For more information on the email engine
centralized configuration settings, see Configuration settings C-D (see page 1168).
For the settings which are not centralized, you should use the EmailDaemon.
properties file to modify these settings.
Performance and configuration settings for the BMC Remedy Email Engine

Settings Centralized Definitions Values Related Related

configuration Functionality Protocol
setting
com.bmc.arsys.emaildaemon. Yes Specifies additional email headers. Default Outgoing SMTP

AdditionalMailHeaders Separate the additional email value: X-
headers with commas. See Adding Loop-Detect
extra custom headers to outgoing
SMTP emails (see page 1503).
com.bmc.arsys.emaildaemon. Yes Specifies the date and time format Incoming All
ARDATE that the BMC Remedy Email Engine Supported
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. Yes Specifies the date format that BMC Incoming All
ARDATEONLY Remedy Email Engine uses for Supported
parsing date strings given in
incoming mails. MMMMM dd, yyyy
is equivalent to December 21, 2009.
com.bmc.arsys.emaildaemon. Yes This setting lets you specify the time Incoming All
ARTIMEONLY format used by BMC Remedy Email Supported
Engine for parsing time strings given
in incoming mails. HH:mm:ss z is
equivalent to 12:08:56 PDT.
com.bmc.arsys.emaildaemon. Yes Specifies the log level for email Incoming and All
ARSystemHandler.level engine based on which the logs are Outgoing Supported
saved in the AR System Email Error
Logs form.
Valid values:
Off (Default)
Severe
Warning
Info
Config
Fine
Finer
Finest
com.bmc.arsys.emaildaemon. Yes This setting indicates whether to Outgoing All

ContentTypeWithCharset send the charset property in the True ( Supported
Content-Type header of an outgoing Default
message. If you do not want the )
charset string to be present in the False
Content-Type header, set this
property to False.
com.bmc.arsys.emaildaemon. Yes Specifies the number of entries to Default Outgoing All

ChunkSize return when the BMC Remedy Email value: 100 Supported
Engine makes a call to the AR
System server.


setting
Note: The
maximum
value is also
100.
com.bmc.arsys.emaildaemon. Yes Specifies whether you can use a Incoming and All
CommaValidAddressSeparator comma as a separator when True ( Outgoing Supported
entering multiple addresses in the To Default
and CC fields. If user names in the )
mail server contain commas, set this False
property to false (usually needed
only when using the MAPI protocol).
For example, if names are stored on
the mail server as:
Smith, John and
Cho, Rick
You would need to use semicolons
to separate the addresses:
Smith, John; Cho, Rick
com.bmc.arsys.emaildaemon. Yes Specifies the amount of time in Default Incoming All

Exchange-Wait-Time milliseconds for which the BMC value: 1 supported
Remedy Email Engine waits before
processing the next incoming
message, when there are more
messages residing on the Exchange
Server.
com.bmc.arsys.emaildaemon. Yes Specifies whether to fetch the user Incoming and All
FetchUserGroupInfoOnDemand and group information about demand True Outgoing Supported
as opposed to loading all users and False (
groups at startup. If there are many Default
users or groups, you might want to )
set this property to true to reduce
the startup time for email.
com.bmc.arsys.emaildaemon. Yes Determines whether the outgoing Outgoing All

getReplyToWithFromAddress message header should contain the True ( Supported
Reply To field and what its value Default
should be. )
getReplyToWithFromAddress is False
not used by default. If you want the
email engine to use this property,
you must add it to EmailDaemon.
properties and set its value to true.
If you add the property but do not
specify a value, it is considered as
false. The effect of using this
property is as follows:
If no values are provided in

the Reply To Address field of
the outgoing mailbox
configuration form and the


setting
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. Yes Specifies whether to wait before Incoming IMAP

IMAPTimeout cancelling an attempt to connect to True
the mail server and generating an False (
error. In case of an IMAP timeout, default
the email engine waits for the )
timeout interval and then marks the
queued message as erroneous.
IMAPTimeout 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.
com.bmc.arsys.emaildaemon. Yes Specifies the duration in number of Incoming IMAP

IMAPTimeoutPeriod seconds to wait before cancelling an
attempt to connect to the mail server
and generating an error. In case of
an IMAP timeout, the email engine
waits for this interval and then marks
the queued message as an
erroneous. IMAPTimeoutPeriod is
properties and set its value to any
positive integer.


setting
com.bmc.arsys.emaildaemon. Yes Specifies the default number of email Default Incoming All
IncomingConnectionRecycleSize messages the email engine receives value: 100 Supported
before the connection is closed and
reopened. In the 5.1 and 5.1.1
releases of the email engine, the
connection with the mail server was
closed only after reading all incoming
messages. Consequently, if the
email engine crashed or hung before
the connection was closed, it was
possible that messages marked for
deletion would not be deleted from
the mail server. This property helps
you avoid that situation.
com.bmc.arsys.emaildaemon. Yes Specifies the message queue size Default Incoming All
IncomingMessagesQueueSize (number of emails). The Receiver value: 100 Supported
module writes messages to the
queue, and the Execution module
reads messages from this queue to
parse and execute. The Receiver
module still writes messages to the
server in AR System Email
Messages form, but the Execution
module reads the message from the
message queue instead of from the
server. This reduces the traffic to the
AR System server and improves the
performance.
com.bmc.arsys.emaildaemon. Yes Specifies the number of instructions Default Incoming All

instructionCacheSize to be stored in the cache, which is value: 20 Supported
used to improve performance. If the
value of this property is set to 15, the
cache already contains 15
instructions, and another instruction
is to be added, then the oldest
instruction is removed to
accommodate the newest one.
Note: If any changes are made to

the BMC Remedy AR System Email
Instructions form, the instruction
cache is flushed based on the setting
of the serverName.Interval property.
com.bmc.arsys.emaildaemon. Yes Specifies the log level for email Incoming and All
level engine based on which the logs are Outgoing Supported
generated in the email.log file.
Valid values:
Off
Severe (Default)
Warning


setting
Info
Config
Fine
Finer
Finest
com.bmc.arsys.emaildaemon. Yes If you run multiple instances of the Incoming and All
Mailboxes email engine on a single server, this Outgoing Supported
property specifies which mailboxes
should the email engine process.
The value of this property should
contain comma-separated mailbox
names; the email engine only
processes these mailboxes. If you do
not specify a value, the email engine
processes all of the mailboxes
configured for the server.
com.bmc.arsys.emaildaemon. Yes Specifies whether the polling interval Incoming and All
MailboxPollingUnitIsMinutes is to be considered in minutes (as True ( Outgoing Supported
configured in AR System Email Default
Configuration) or seconds. The email )
engine interprets the value of this False
property as follows:
true — Consider the polling

interval in minutes.
false — Consider the polling
interval in seconds.
Note: Whatever measure of unit you

select applies to all configured
mailboxes that are enabled.
com.bmc.arsys.emaildaemon. Yes Specifies the attachment types that Incoming All

MaxAttachSize and com.bmc. you want to permit in an email True Supported
arsys.emaildaemon. message and the maximum size of False (
MaxAttachSizeFileExtensions each attachment.MaxAttachSize Default
specifies the maximum size limit for )
attachments, whereas
MaxAttachSizeFileExtensions
specifies the file types by using
comma-separated extensions. These
properties must be used together to
impose limits on email attachments
of specific file types. For example, to
set the maximum size of .doc, .pdf,
and .xls attachments to 1000000
bytes (1 MB), use the following
syntax: com.bmc.arsys.
emaildaemon.
MaxAttachSize=1000000 com.bmc.
arsys.emaildaemon.


setting
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. Yes The email engine interprets the value Incoming and MBOX
MBOXFromLineWith-At-The- of this property as follows: True Outgoing
Rate-Sign False (
true — BMC Remedy Email default
Engine fetches only those )
messages that contain the @
sign in the "from line" (from
address).
false — BMC Remedy Email
Engine fetches all the
messages.
com.bmc.arsys.emaildaemon. Yes Specifies the interval in minutes Default Incoming and All
Monitor between checks to see if all the value: 30 Outgoing Supported
threads are functioning properly. minutes
Note: If the monitoring system

detects that a thread has failed, it
restarts the thread.
com.bmc.arsys.emaildaemon. Yes Specifies the number of sender Permissible Outgoing All

NumberOfSenderThreads threads that the email daemon uses range of Supported
for each outgoing mailbox. The values: 1
optimum number of threads depends through 20
on many factors including the Default
number of mailboxes, the hardware value: 4
configuration, and so on.
com.bmc.arsys.emaildaemon. No Specifies the size of the queue that Default Outgoing All
OutgoingMessagesQueueSize the email daemon maintains for value: 100 Supported
outgoing messages. The optimum
number of message queue size to be
specified depends on the load on the
email daemon.
Note: This value is used to

determine when to query the
database. If you set a very high
value, the database is queried too
often, which might reduce the
performance.
Yes Incoming POP3


setting
com.bmc.arsys.emaildaemon. Specifies whether to wait before True

POP3Timeout cancelling an attempt to connect to False (
the mail server and generating an default
error. In case of an POP3 timeout, )
the email engine waits for the
POP3Timeout 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. When you set
POP3Timeout to true, the
POP3TimeoutPeriod property is
used.
com.bmc.arsys.emaildaemon. Yes Specifies the duration in number of Incoming POP3

POP3TimeoutPeriod seconds to wait before cancelling an
an POP3 timeout, the email engine
erroneous. POP3TimeoutPeriod is
positive integer.
com.bmc.arsys.emaildaemon. No Specifies the port number for remote Default Incoming and All
RMIPORT = 1100 method invocation (RMI). This value: 1100 Outgoing Supported
feature is used with the
EmailAdminAgent.jar file to stop,
suspend, resume, or change logging
level of the email engine at runtime.
com.bmc.arsys.emaildaemon. Yes Specifies whether to retain Outgoing All

SaveSentItem messages in the Email Messages True ( Supported
form after sending. To delete sent Default
messages from the Email Messages )
form, set this property to False. False
com.bmc.arsys.emaildaemon. Yes Specifies the number of security Default Incoming and All
securityCacheSize keys to be stored in the cache. If the value: 20 Outgoing Supported
cache already contains 15 security
keys, and another key is to be
added, then the oldest key is
removed to accommodate the
newest one.


setting

Security form, the security cache is
flushed based on the setting of the
serverName.Interval property.
com.bmc.arsys.emaildaemon. Yes Specifies the number of outgoing Default Outgoing All

SendEmailSetSize emails to query at a time. value: 100 Supported
com.bmc.arsys.emaildaemon. No Specifies a string if your AR System

serverName.Authentication server requires authentication
information before handling
requests.
com.bmc.arsys.emaildaemon. No Specifies the interval in minutes after Default

serverName.Interval which to check with the server for the value: 30
following:
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. No Specifies the language that the email Default

serverName.Language engine must use. value: en_US
com.bmc.arsys.emaildaemon. No Specifies the RPC port number that

serverName.RPC the AR System server uses if you
have configured a private server to
be used with the email engine.
com.bmc.arsys.emaildaemon. No Specifies the TCP port number that

serverName.TCP the AR System server uses if it is not
using the BMC Remedy AR System
portmapper.
com.bmc.arsys.emaildaemon. No Specifies the name of the AR

Servers System server that the email engine
interacts with.
com.bmc.arsys.emaildaemon. Yes Specifies whether to wait before Outgoing SMTP

SMTPTimeout cancelling an attempt to connect to True
the mail server and generating an False (
error. In case of an SMTP timeout, Default
)


setting
the email engine waits for the

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.
Note: If you use the email engine

properties com.bmc.arsys.
emaildaemon.SMTPTimeout and
com.bmc.arsys.emaildaemon.
SMTPTimeoutPeriod, you might
encounter issues with outgoing e-
mail 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 for which no workaround is
available.
If you use these properties, BMC

recommends the following
SMTPTimeoutPeriod values to
avoid encountering this issue:
40000 messages — 30
seconds
seconds
seconds
These settings can work
correctly with the maximum
permissible number (20) of
Sender threads. However,
BMC recommends using a
value that is optimum for your
configuration.
com.bmc.arsys.emaildaemon. Yes Specifies the duration in number of Outgoing SMTP

SMTPTimeoutPeriod seconds to wait before cancelling an
an SMTP timeout, the email engine


setting
erroneous.SMTPTimeoutPeriod is
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.
Recommendation for using the

SMTP timeout properties
If you use these properties, BMC
recommends the following
SMTPTimeoutPeriod values to
avoid encountering this issue:
seconds
seconds
seconds
These settings can work
correctly with the maximum
permissible number (20) of
Sender threads. However,
BMC recommends using a
value that is optimum for your
configuration.
com.bmc.arsys.emaildaemon. Yes Specifies whether to process Outgoing All

SortMessages messages with a higher priority True Supported
setting first. False (
Default
)
com.bmc.arsys.emaildaemon. Yes Specifies whether to store Incoming All

StoreInstructions instructions and instruction True supported
parameters in the AR System server. False (
If set to true, the email engine Default
retains data in the Email Instructions )
and Instruction Parameters forms for
troubleshooting. Then, you must
delete this data explicitly. The
Execution module in the BMC


setting
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. Yes This property is not available by Incoming and All

SynchronizedLoggingMode default. You can add it if required. If True Outgoing Supported
this property is not present in False (
EmailDaemon.properties, or if it is Default
present but set to false, the bulk API )
logging mode is used. If this property
is present in EmailDaemon.
properties and its value set to true,
then the synchronized logging mode
is used.
Note: The email engine's

performance might degrade when
synchronized logging is enabled,
because all the email engine threads
are suspended while processing the
synchronized logs. Synchronized
logging continues to occur
periodically, and control is restored
to the threads only after the logging
is over.
com.bmc.arsys.emaildaemon. Yes Specifies the number of email Default Incoming All

templateCacheSize templates to be stored in the cache value: 20 Supported
to improve the performance. If the
cache already contains 15
templates, and another template is to
be added, then the oldest template is
removed to accommodate the
newest one.

Templates form, the templates cache
is flushed based on the setting of the
com.bmc.arsys.emaildaemon. Yes Specifies whether an <a href> tag is Outgoing All

URLWithHrefTag placed around a URL in an HTML True ( Supported
message. If the setting is true, the Default
<a href> tag is used. If the setting is )
false, the URL is not enclosed in an False
<a href> tag.
com.bmc.arsys.emaildaemon. Yes Outgoing All

UseNameIfNoEmailAddress Supported


setting
Specifies whether to retain display True (

names that do not have email Default
addresses associated with them in )
the To, CC, or BCC fields. If the False
setting is true, the display names are
not removed from the To, CC, or
BCC fields. If the setting is false, the
display names are removed from the
To, CC, or BCC fields.
Note: The email engine checks for

email addresses associated with
display names only on the User form
and not on the Exchange server.
com.bmc.arsys.emaildaemon. Yes Specifies the number of users Default Outgoing All

UserChunkSize (records from the User form) to value: 5000 Supported
retrieve from the AR System server
at one time. This setting can be used
to tune the email engine's
performance.
com.bmc.arsys.emaildaemon. Yes Specifies the email address of the Default value Incoming All
AdminAddresses administrator. If a database is set to the Supported
transaction fails while storing an administrator
incoming message, the email engine address
forwards the original mail to this specified
email address, so that it is retained. during
An example of a transaction failure installation.
could be when the database is full
and cannot save anymore incoming
email messages. You can specify
multiple addresses 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.
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. (see page 1605)
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 (see page 1467).
Saving outgoing notifications in MAPI

If you use the MAPI email protocol and you want to save messages on the Exchange server, you
must configure your outgoing mailbox to save outgoing notification emails in an Outlook folder.
To save outgoing notifications, add the following line to the EmailDaemon.properties file:
ARSystemServer.MAPI_Sent_Folder=folderName
ARSystemServer is the name of the AR System server associated with the Email Engine.
folderName is the name of the folder that stores the outgoing notification emails. For
example, enter Sent Items to save messages to your Sent Items folder in Microsoft
Outlook.
Changing the default time interval

When the email engine starts, it retrieves all the entries in the AR System Email Mailbox
Configuration form and creates incoming and outgoing mailboxes. Every 30 minutes, the email
engine automatically queries the form for changes to the form entries and updates the information.
To enable changes to form entries before the next default query time, stop and restart the email
engine.
Note
Changes to the Status field are not reflected automatically. If you have changed the
value of this field, you must restart the email engine for the change to take effect.

To shorten the default time interval in the EmailDaemon.properties file, set the polling parameter.
For example, shorten the time to 5 minutes: ServerName.Interval = 5.
For more information about this property or the EmailDaemon.properties file, see Settings in the
EmailDaemon.properties file (see page 612).
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. (see page 684)
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 (see page 4661).
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 (see page 626).
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 (see page 627).
7. After the time specified for the incoming mailbox's polling interval, open the AR System
Email Messages form in Search mode.
8. Select a mailbox name and perform a search. The results table displays the entry
corresponding to the message you sent.
9. Double-click the entry to open the form containing the information for that entry.
10. Make sure that the subject line and content in the form are the same as the subject line and
content of the test email that you sent, which indicates a successful test.
Configuring incoming mailboxes

Based on the information that you enter in the AR System Email Mailbox Configuration form, the
Email Engine polls incoming mailboxes for new messages, processes the messages, parses the
contents if necessary, and performs the actions specified in the messages, such as modifying
requests or executing queries.
Incoming mailboxes support the MAPI, POP3, IMAP4, and MBOX mail protocols.

The following topics provide information about how to configure the basic and advanced properties
of incoming mailboxes:
Configuring basic incoming mailbox properties (see page 628)

Configuring advanced incoming mailbox properties (see page 629)
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.
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.
MAPI protocol requires Microsoft Outlook 32-bit client, irrespective of

the OS bit size.
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 (see
page ).
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
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 (see page 1565) and Types of email templates (see page 1560).
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
(see page ).
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 (see page
1567).
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.
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
(see page ).
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
(see page 1567).
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.
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 (see
page 632)
To start and stop the Email Engine manually on Windows from the command line (see page
633)
To start and stop the Email Engine manually on UNIX (see page 633)
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.
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.
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

Identifying the Email Engine component

BMC Remedy Email Engine uses the following properties to create a unique component name:
com.bmc.arsys.emaildaemon.companionservername
com.bmc.arsys.emaildaemon.RMIPORT
The naming format is:
companionServerName:RMIPort
where,
companionServerName specifies the companion server name for Email Engine
RMIPort specifies the port number for remote method invocation (RMI)
For example, myhostname.com:1100
Modifying the companionservername or RMIPort properties

To modify the value of companionservername or RMIPort, perform the following steps:
1. Stop BMC Remedy Email Engine.

See Stopping and starting the Email Engine (see page 632).
2. Open the EmailDaemon.properties file.
3. Modify the values as needed.
4. Save your changes to the EmailDaemon.properties file and close the file.
5. Open the AR System Configuration Component form in search mode.
For more information about this form, see Centralized configuration system forms (see page
1146).
6. Search for the Email Engine component by using the following search criteria:
a. Type = com.bmc.arsys.emaildaemon
b. Name = companionservername
7. Modify the component name to reflect the changes made in the EmailDaemon.properties
file.
For example, for the myhostname.com companion server, if you changed the RMIPort (in
the EmailDaemon.properties file) from 1100 to 1200, then the new component name will
be myhostname.com:1200.
8. Restart BMC Remedy Email Engine.
Configuring BMC Remedy Flashboards

The following topics provide information about configuring BMC Remedy Flashboards:
Setting up flashboard update intervals (see page 635)

Starting or stopping the Flashboards server manually (see page 636)

Setting up a headless environment with Tomcat to display flashboards (see page 637)
Configuring the display properties for a flashboard (see page 637)
Modifying the config.properties file for flashboards (see page 644)
AR System Administration - Flashboard Server Configuration (see page 645)
Multiple Flashboards servers and AR System servers (see page 646)
Setting up flashboard update intervals

The mid tier displays flashboards in a web browser and generates Flashboards images from
information in the mid tier cache. You can change mid tier cache update times from Flashboards
Settings in the BMC Remedy Mid Tier Configuration Tool.
To change mid tier cache update times
1. Enter the following URL to open the BMC Remedy Mid Tier Configuration Tool:
http://<webServerThatSupportsFlashboards>/arsys/shared/config/config.jsp
Note
The default login password is arsystem.
2. Click Cache Settings to open the Cache Settings page.
Cache Settings page in BMC Remedy Mid Tier Configuration Tool

3. Make changes to the Update Flashboards Definition Interval settings.

The Flashboards definition is the graph and data representation. The definition interval is
the interval (in seconds) at which the server updates the Flashboards cache information.
The default value for both Windows and UNIX is 0, which means that caching is disabled.
4. Click Save Changes to save the new values.

To configure BMC Remedy AR System to view flashboards using the default URL
path
1. In a browser, from the server that contains the flashboard, open the BMC Remedy AR
System Administration Console, and click System > General > Server Information.
The BMC Remedy AR System Administration: Server Information form appears.
3. In the Default Web Path field, change the default URL path to:
http://<hostName>:port/arsys
where hostName is the location where you installed the BMC Remedy Mid Tier and port is
the port number. The port number is optional.
For example, if your host name is abc, and your port number is 230 (optional), your default
URL path would be: http://abc:230/arsys
Note
Refresh your flashboard to view the most recent historical, summary, and real-time
data.
Starting or stopping the Flashboards server manually

Use the Flashboards server to collect historical data.
To start or stop the Flashboards server on Windows
1. Access the Services screen.

a. Choose Start > Settings > Control Panel.
b. Double-click Administrative Tools.
c. Double-click the Services icon.
2. Select the Flashboards server.
3. Select Action > Start or Action > Stop, as required.
To start or stop the Flashboards server on UNIX or Linux
1. Change directories to the installation directory of that server.

2. Enter the following commands to start or stop the Flashboards server:
server.sh start
or
server.sh stop

If you are running two Flashboards servers on the same computer and you enter the server.
sh stop command, both servers will stop. To stop only one Flashboards server, include the
port number in the command as given below:
server.sh stop -p <portNumber>
Setting up a headless environment with Tomcat to display

flashboards
If you use a terminal to reach a headless UNIX system where you have installed the web server
and mid tier, you might receive error messages when accessing flashboards through a browser.
To make sure that flashboards work from a headless UNIX environment, you must set Java VM
options on the servlet engine that controls BMC Remedy Mid Tier.
To set Java VM options on the servlet engine
1. In the catalina.sh file, add the following options for JAVA_OPTS near the top of the file:
-Djava.awt.headless=true
-Dsun.java2d.fontpath= sdkInstallDirectory/jre/lib/fonts
Example
JAVA_OPTS="-Djava.awt.headless=true -Dsun.java2d.fontpath=/usr/jdk1.
5.0_10/jre/lib/fonts"
2. Restart Tomcat for this change to take effect.
Use a similar procedure to add VM options to other servlet engines. See your respective server
vendor's documentation for information about configuring Java options.
Configuring the display properties for a flashboard

To ensure a similar look and feel across BMC products, the default format of BMC Remedy
Flashboards has the same color scheme and look as the BMC Dashboards product.
BMC Remedy Flashboards uses Adobe Flash technology. In leveraging the Adobe Flash
technology, the new BMC Remedy Flashboards product provides:
A more exciting UI.

Off-loading of the chart rendering to the client side (browser side)--thus freeing the mid tier
to do more processing.
More client-side interactions such as step zoom in and zoom out; dynamic chart, legend,
and color change; and full-screen view.
Note
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 (see page 638)

Additional flashboard properties (see page 642)
Enable the Embedded property (see page 643)
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 (see
page 2706).)
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
(see page 2706).)
The "Formats for flashboards" (see page 639) 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 (see page )
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 7.1.00/7.0.01 color and
scheme format
Axis
Show X Axis + + +


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


based
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
Axis line visible. By default, the 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
Axis line visible. By default, the value is set to 0.

Property Description
Show Option to display labels above each horizontal bar of the capacity flashboard. If the value is set to 0, the vertical axis
Label labels are displayed outside chart at the default position. If the value is set to 1, the vertical axis labels are displayed
Inside inside the chart above each bar.
Note
This property is applicable for horizontal capacity flashboard only and it is ignored for other flashboards.
Note
The properties mentioned in the table are available for any flashboard type.
Enable the Embedded property

You can enable the Embedded property for the flashboard to embed the flashboard on the
window. Embedded flashboards do not display distinct boundaries and the background color.
These support transparency on the form and do not display borders. You can see the text
description within the flashboard. Embedded flashboards do not contain the following controls.
Show Legend
Full Screen
Options
Embedded Flashboard

However, you can right-click on the embedded flashboard to open a context menu and view these
options.
Note
Embedded flashboards do not support zoom functionality. When you view the embedded
flashboard using BMC Remedy Mid Tier 7.6 or earlier, it appears like a regular flashboard
with borders and controls.
To enable the Embedded property for flashboard, in BMC Remedy Developer Studio Properties
window, under the Chart section, set the flashboard property Embedded to 1. By default, the
value is set to 0.
Modifying the config.properties file for flashboards

This section provides the details on modifying the config.properties file for flashboards. You can
manually change the default behavior of flashboards by changing the settings in the 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 (see page 638).
Settings used to change the flashboards format
Setting Description
flashboards. Defines which default format to use when displaying flashboards. The options are:
showgraphinflash=[0 or 1]
0 — Use image-based format.
1 — Use Adobe Flash format.
flashboards. The minimum flashboard width below which a flashboard is rendered by using image-based
min_flex_width=260 technology. The default is 260.
flashboards. The minimum flashboard height below which a flashboard is rendered by using image-based
min_flex_height=200 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
AR System Administration - Flashboard Server Configuration

You configure the BMC Remedy Flashboards server by using the AR System Administration:
Flashboard Server Configuration form (AR System Administration Console > System > General
> Flashboard Server Configuration).
Note
The server.config file allows you to configure only the Flashboards server name, port,
and password. To configure the Flashboards service startup properties, the refresh
interval properties, the logging options, and other properties, you must use the
Flashboards Configuration form.
The following table describes the fields in the Flashboard Configuration form:
Field Description
Component Select a BMC Remedy Flashboard server to configure.

name
Flashboard Service Startup
Wait for The interval (in seconds) for which the BMC Remedy Flashboard server waits for the BMC Remedy AR System
Server to server to start up. The default value is 300 seconds.
Start
Server The number of times the Flashboards server tries to connect to the BMC Remedy AR System server. The
Reconnect Flashboards server waits for the BMC Remedy AR System server to start up and tries to connect. If the
Attempts connection fails, the Flashboards server continues trying based on number of attempts value. The default value is
10.
Intervals
The interval (in seconds) after which the BMC Remedy Flashboard server checks the changes to Flashboards
definitions. The default value is 1,800 seconds.

Field Description
Flashboard
Definition
Refresh
Interval
Config The interval (in seconds) after which the BMC Remedy Flashboard server checks for the changes to the server.
File Check conf file. The default value is 60 seconds.
Interval
Logging Properties
Log To The method by which you want to view log files:
FILE – Data is saved to a file in the specified log directory.

CONSOLE – The log entries are directed to the stderr (System.err) of your servlet engine.
The default value is FILE.
Log File Specifies the log file name. The default value is arfbserver.log.
Name
Maximum The maximum size (in kilobytes) for the log file. The default value is 100 KB.
File Size
Maximum The maximum number of backup (.bak) log files to be allowed when the log file reaches the Maximum File Size
Backups value and a new log file is created. The default value is 10.
Log Level The logging level:
BASIC – The minimum log level which logs errors.

INFO – The log level which logs errors with information
DEBUG – The maximum log level which gives detailed log information.
The default value is BASIC.
Log Format The log output is generated using Java log4j pattern layout.
The default value is <%t> <%c> <%d> <%l> <%m> %n. For more information about the log4j pattern layout, see
Pattern layout.
Log The type of information to be stored in the log file:

Category
Alarm
Flashboard Server — Flashboard server calls logging is stored in the log file.
Flash Util — Flashboard server classes logging is stored in the log file.
By default, all the logging types are selected.
Others
RMI Specifies the value of the Remote Method Invocation (RMI) port for the selected BMC Remedy Flashboards
Registry server.
Port
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.
To manually start a BMC Remedy Flashboards server
1. Change the value of the Remote Method Invocation (RMI) port using the Flashboard
Server Configuration form to any port that is not in use. See AR System Administration -
Flashboard Server Configuration (see page 645).
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 starting the server, enter the RMI port values into the Flashboards Server
Configuration form corresponding to each BMC Remedy Flashboards server, as follows:
Flashboard Server Configuration > component 1
Flashboard Server Configuration > component 2
The port numbers must correspond to unused ports. See AR System Administration -
Flashboard Server Configuration (see page 645).
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 (see page 651)

2. Setting-up BMC Remedy Migrator (see page 652)
3. Adding AR System server into server account (see page )
4.
4. Adding a licensed AR System server in BMC Remedy Migrator (see page 650)
5. Adding or transferring BMC Remedy Migrator license to an AR System server (see page 651
)
6. Removing an AR System server and its BMC Remedy Migrator license from view (see page
648)
Removing an AR System server and its BMC Remedy

Migrator license from view
Removing a server and its BMC Remedy Migrator license from the servers list makes the server
inaccessible to BMC Remedy Migrator, but it does not remove the license from the server (or from
the local BMC Remedy Migrator license file if the server is version 4.5.2 or older). It only removes
the server from the local machine and it can no longer be viewed.
To remove a server from view
1. In BMC Remedy Migrator, select Tools > Licenses.

2. In the Server Licenses dialog box, select a server, and click Remove.
3. In the message box, click Yes to confirm the license removal, or No to keep the license in
view.
4. After confirming the server removal, indicate whether you want to remove the server from
the local cache.
By doing this, you can remove servers from the Server Licenses list, but still keep some or
all of the servers cached.
Note
If you add a removed server back to the servers list later, the definitions are
retrieved the first time you log on to the server.
Adding AR System server into server account

Using the Accounts dialog box, you can add, modify, or delete server and limit access to users
from the available servers.
After you log on to BMC Remedy Migrator and open the Accounts dialog box, either a check mark
or an X appears next to each server name.
A green check mark indicates you can connect to the server.

A red X indicates you cannot connect to the server, even if the server has been licensed.
The following steps show how to manage your server accounts as an administrator.

To add AR System server into server account
1. Select Tools > Accounts to open the Account dialog box, which shows the servers that
have been added.
If the Accounts menu selection is unavailable, you must provide login information before
proceeding.
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 Click User Manager. Click Add to add a new user, or select a name in the Users list and click
Users list Modify to modify the user account.
Note
For each user to have their own server list, you must include a specific home directory
for that user in the directory path.

View port columns Select Advanced Server Properties. Select a server and click a column and type a port
for firewall support number or private server number:
AR TCP Port represents the port number of the AR System server.
AR RPC # represents the program number of the specified AR System server. This
number allows you to connect to a private server behind the firewall.
Warning
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 (see page 85) 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 (see page 648).
Adding a licensed AR System server in BMC Remedy Migrator

When you have logged into BMC Remedy Migrator, you can add a licensed AR System server.
One AR System server license is issued for each AR System server you want to work with using
BMC Remedy Migrator. There is no limit to the number of clients on which you can install BMC
Remedy Migrator.
To add a licensed AR System server in BMC Remedy Migrator
1. In BMC Remedy Migrator, select Tools > Licenses to open the Server Licenses dialog box.
Server Licenses dialog box in BMC Remedy Migrator

2. Click Add.
3. Select a server from the list, and click OK.
If the server is properly licensed, it is added to the list in the New Licenses section of the
Server Licenses dialog box.
4. Click Done.
For information about removing, importing, purging, or viewing the license, see Adding or
transferring BMC Remedy Migrator license to an AR System server (see page ).
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 (see page
). 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 (see page 650)
.
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 (see page
4761).
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 (see page )
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 (see page 280).
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 (see page 85).

Configuring the Assignment Engine server

settings
You can use the AR System Assignment Engine: Server Settings form to enable the
Assignment Engine logs and configure the logging settings.
AR System Assignment Engine: Server Settings form

To configure the AR System Assignment Engine: Server Settings form, navigate to BMC
Remedy AR System Administration Console > Quick Links > Assignment Engine
Administration > Sever Settings.
Important
Note the following points when modifying the form:
The Max Back-up Index value defines the maximum number of backup (.bak) log
files that can be created when the log file reaches the Max Log File Size value
and a new log file is created.
If you modify the Number of Threads value, you must restart the server to
apply changes.
You cannot modify the Assignment Engine logging settings using the ar.cfg file.
The following Assignment Engine settings are now obsolete:
AE-Trace
AE-Trace-File
AE-Log
AE-Log-File
AE-Worker-Thread
Assignment Engine log file format

The format of the Assignment Engine log files is consistent with the AR System server log files.
The actual content may vary according to Assignment Engine logging needs. The following sample
shows an Assignment Engine log file entry:
<ASSN> <TID: 0000000314 > <USER: Remedy Application Service>

<Overlay-Group: 0 > /* Mon Aug 25 2014 14:59:13.2000 */
INFO Main Thread is waiting for Cache to be built for the first time.

For more information, see Assignment Engine logs (see page 4315).
Configuring BMC Remedy Single Sign-On

BMC Remedy Single Sign-On can be configured for authentication with BMC Remedy AR System
Server and SAML.
Important
User credentials and authentication tokens are security sensitive data. Hence to protect
such data, HTTPS has to be configured.
For standalone installations, HTTPS has to be configured on the Tomcat server and for
High Availability installations, HTTPS has to be configured on the load balancer.

The following topics provide information for configuring BMC Remedy Single Sign-On.
Using BMC Remedy AR System for Authentication (see page 655)

Using SAMLv2 for authentication (see page 656)
Using Kerberos for Authentication (see page 664)
Using LDAP for authentication (see page 675)
Managing Server Configuration (see page 676)
The following video provides information about configuring BMC Remedy Single Sign-On for
authentication.

To integrate BMC Remedy Single Sign-On with supported BMC products, see Integrating
BMC Remedy Single Sign-On with other products (see page 812).
Related topics
Security concepts
BMC Remedy Single Sign-On agent supporting multiple servers (see page 81)
Using BMC Remedy AR System for Authentication

BMC Remedy Single Sign-On allows group information associated with BMC Remedy Action
Request System (BMC Remedy AR System) server users to be retrieved and provided to BMC
products. The BMC Remedy AR System authentication module and the BMC Remedy AR System
user store are designed to be used together to provide additional information for users
authenticated against the AR System server.
To ensure secure authentication, HTTPS has to be configured. For standalone installations,

HTTPS has to be configured on the Tomcat server and for High Availability installations, HTTPS
has to be configured on the load balancer.
Note

The BMC Remedy AR System user store provides read-only access to the user
information stored in the AR System server and read-only access to user and group lists
and memberships.
To configure BMC Remedy AR System for authentication
1. Log on to the BMC Remedy Single Sign-On Admin console.

2. Click Realm.
3. In the List of Realms window, edit an existing realm, or add a new realm by entering the
following details:
Authentication Type: AR
Host: [AR host]
Port: [AR port]
Transformation: Select a transformation from the drop down list.

To integrate BMC Remedy Single Sign-On with BMC Remedy AR System, see Integrating BMC
Remedy Single Sign-On with BMC Remedy AR System (see page 812).
Related topics
Orientation
Security concepts
Troubleshooting authentication issues (see page 4773)
Using SAMLv2 for authentication

Security Assertion Markup Language (SAML) is an XML-based OASIS standard for exchanging
user identity and security attributes information. It uses security tokens containing assertions to
pass information about a principal (usually an end user) between an identity provider (IdP) and a
web service.
SAML V2.0 is implemented by grouping a collection of entities to form a Circle of Trust. The Circle
of Trust is composed of a Service Provider (SP) and an IdP. The IdP authenticates users and
provides details of the authentication information to the SP. The SP hosts services that the user
accesses.

In a Circle of Trust, BMC Remedy Single Sign-On is normally configured as an SP for BMC
products. The Circle of Trust is then completed with an IdP to provide authentication for the
federated single sign-on.
The following table briefly outlines the steps to configure BMC Remedy Single Sign-On for
Kerberos authentication.
1. Configuring BMC Remedy Single Sign- In the BMC Remedy Single Sign-On Admin console, you must configure BMC
On as a service provider (see page Remedy Single Sign-On as a service provider to handle SAML authentication.
657)
2. Configuring ADFS as an IDP for After you configure BMC Remedy Single Sign-On as the local service provider,
SAML authentication (see page 660) you must configure ADFS as an identity provider to handle SAML
authentication.
Related topics
Orientation
Security concepts
Configuring BMC Remedy Single Sign-On as a Service Provider

In a Circle of Trust (COT), BMC Remedy Single Sign-On is normally configured as a Service
Provider (SP) for BMC products. The Circle of Trust is then completed with an Identity Provider
(IdP) to provide authentication for the federated single sign-on.
To configure SAML for authentication

2. Click General.
3. Enter the details listed in the following table:
Field Parameters Description
Basic tab
Cookie Cookie The default cookie domain value is the network domain of the computer on which you are
domain installing the server. The default cookie domain specifies the most restrictive access. This
value is used to control cookie visibility between servers within the domain.
This cookie domain must be the same for both BMC Remedy Single Sign-On server and its
integrated application server.
Session Max Time after which your session is logged out, even when you are active. When this value is
Settings session selected, time constraints are automatically enforced. The default is 24 hours.
time
The value for maximum session time is usually 4, 8, or 12 hours.
Log Server Log Select the level of log details to be displayed from the drop-down list. The options are:
Level ERROR

WARN
INFO
DEBUG
TRACE
Advanced tab
Cookie Cookie The cookie name is automatically created at installation and based on the timestamp.
name Timestamp is the time the database is created during BMC Remedy Single Sign-On
installation.
Enable Select the check box to enable secured cookie.

Secured
Cookie
SAML SP Entity ID The prefix of SP entity ID. Each realm using SAML authentication will have a unique SP entity
Service ID based on the value of this property with realm ID appended.
Provider
External The URL for IdP to redirect to for sending SAML response.
URL
Signing The certificate used to sign a SAML request if Sign Request is selected.
Certificate
4. Click Realm.
5. In the Realm list window, edit an existing realm or create a new realm by entering the
following details.
General tab
Field Description
Realm Example: Yourcompany.

ID
Realm Host name of an external application (for example, BMC Remedy Mid Tier or BMC MyIT) that is integrated
Domain with BMC Remedy Single Sign-On. The realm name is automatically identified by the agent according to realm
(s) domains and the application URL. Separate multiple names using commas.
Examples: firstcompany.midtier.bmc.com, secondcompany.midtier.bmc.com, thirdcompany.midtier.bmc.com
Final Enter the URL to which the user will be redirected to after logging out from all applications integrated with
Logout BMC Remedy Single Sign-On.
URL
Authentication tab
Field Description
Authentication Select the SAML option.

Type
Identity To import IdP metadata, click the Import button.

Provider
IdP Entity ID Obtained from an external IdP provider such as ADFS or Okta.
Examples:http://adfs.local/adfs/services/trust, http://www.okta.com/exk4mi22tbfhiAnIn0h7

Field Description
Login URL Obtained from an external IdP provider such as ADFS or Okta.
Examples:https://adfs.local/adfs/ls, https://dev-726770.oktapreview.com/app
/bmcdev726770_oktaidp_1/exk4mi22tbfhiAnIn0h7/sso/saml
Sign Request If the IdP requires that the authentication request be signed, select this option.
Sign If BMC Remedy Single Sign-On requires a signed response from the IdP, select this option.
Response BMC Remedy Single Sign-On validates the signature from the authentication response.
Compress To compress the SAML message to save space in the URL, select this option.
Request
User ID Enter the user ID attribute. This value will be used to retrieve the user id from the specified attribute in
Attribute the SAML response. If it is not specified, the NameID will be used as the user id.
Transformation Select an option (NONE, RemoveBMCDomain, RemoveEMailDomain, TO_UPPER_CASE,

TO_LOWER_CASE) from the drop-down list.
If custom transformation plugins are provided, more options would be available.
NameID Select an option from the drop-down list.

format Defines the name identifier formats supported by the service provider. Name identifiers are a way for
providers to communicate with each other regarding a user.
The Name ID format list is an ordered list, the first Name ID has the highest priority in determining the
Name ID format to use. If the user does not specify a Name ID to use when initiating single sign-on,
the first one in this list is chosen and supported by the remote Identity Provider.
A persistent identifier is saved to a particular user's data store entry as the value of two attributes. A
transient identifier is temporary and no data will be written to the user's persistent data store.
Note:
For linking user accounts from SP and IdP (Remote Identity Provider) together, after logging in, the
persistent nameID format must be on the top of the list.
Auth Context Select an option (exact, minimum, maximum, better) from the drop-down list.
Compare
Auth Context Enter the authentication context.
This attribute maps the SAMLv2-defined authentication context classes to the authentication level set
for the user session for the service provider.
Auth Issuer Enter the Auth Issuer details. This 'issuer' element is used by SAML authentication request XML to
inform the IdP about the entity ID of the service provider for this request.
If the value is not specified, by default SP entity ID of current realm will be used as Issuer in SAML
authentication request.
Force Select the check box to enforce the authentication.

Authentication
Service To view data, click the View Metadata button.

Provider
Template Authentication Request Template - Select Default or Custom to edit the template used for
SAML authentication request.
SP Metadata Template - Select Default or Custom to edit the service provider metadata
template. This metadata is generated when you click the View Metadata button against Service
Provider.
6. Click Save to save the details.


To configure an IdP, see Configuring ADFS as an IdP for SAML authentication (see page 660).
Related topics
Orientation
Security concepts
Configuring ADFS as an IdP for SAML Authentication

After you configure BMC Remedy Single Sign-On as the local service provider and AD FS as the
remote identity provider in the BMC Remedy Single Sign-On Admin Console, you must configure
AD FS to handle the SAML protocol.
You must perform the following activities to configure ADFS.
Import Certificates (see page 660)

Configure Relying Party Trust (see page 661)
Modifying the secure hash algorithm (see page 662)
Configuring claim rule (see page 662)
Export ADFS certificates (see page 663)
Import Certificates
To import certificates
1. Go to the AD FS server
2. Import the following certificates via the mmc console to Trusted Root CA:
SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On is deployed
Click here to read the steps to import the certificates.
a. From the Run dialog box, type mmc to open Microsoft Management Console
(MMC).
b. Open the File menu and click Add/Remove Snap-in…
c. Select Certificates from the list of available snap-ins and click Add.
The Certificates snap-in dialog box is displayed.
d. Select My User Account, and click Finish and OK.
e. Open Personal>Certificates from the explorer panel.
f. On the Action menu, point to All Tasks, and then click Import to start the Certificate
Import Wizard.
g.
g. Import the SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On
is deployed and the Signing certificate.
h. Open Trusted Root Certification Authorities>Certificates from the explorer panel.
i. Import the SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On
is deployed.
SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On is
deployed.
Click here to expand to read the steps to export the certificate.
a. When you open the BMC Remedy Single Sign-On URL, click on the padlock
symbol in the address line of the browser.
b. In the Certificate window, click on the Details tab.
c. Click Copy to File.
d. In the Certificate Export Wizard, click Next.
e. In the displayed page, select "DER encoded binary X.509 (.CER)".
f. Click Next.
g. Provide a name for the file and include the path in the file name.
Note
Note: The Common Name (CN) attribute of this certificate must be the same
as the FQDN of the BMC Remedy Single Sign-On server.
Signing certificate (optional) - The certificate (webapps/rsso/WEB-INF/classes/cot.

jks) that will be used to sign the specified SAML messages. This certificate is
available in the Admin UI (General > Advanced > SAML Service Provider > Signing
Certificate) of BMC Remedy Single Sign-On.
Configure Relying Party Trust
1. On the AD FS server, open the AD FS 2.0 Management application.

2. On Trust Relationships tab, click Relying Party Trusts.
3. Click Add Relying Party Trust. A wizard appears.
4. Configure the following parameters:
a. Select Import data about the relying party published online or on a local network
.
b. Copy the metadata web link that you received from the BMC Remedy Single Sign-
On. For example, https://rssoexample.bmc.com:8443/rsso/getmetadata.jsp?
tenantName=<name of the corresponding tenant>.

Note
If you see a warning, you can ignore it. However, if you are unable to
proceed with the configuration, the certificates were not exchanged
correctly. Contact the BMC Remedy Single Sign-On administrator for more
information.
In case of specific network settings when AD FS and BMC Remedy Single
Sign-On servers are not able to connect using SSL protocol, this error
message may be normal and can be ignored. In this case, you can import
the SP metadata into AD FS offline using an XML file.
c. Click Next.
d. Type rsso-sp for the display name, and click Next.
e. Select ADFS 2.0 profile, and click Next.
f. Select Permit all users to access this relying party, and click Next.
g. Clear the Open the Claims when this finishes check box.
h. Click Close.
After closing the Add Relying Party Trust Wizard window, sp appears in the Relying Party Trusts
list.
Modifying the secure hash algorithm
1. Right-click rsso-sp, and select properties.

The rsso-sp Properties dialog box appears.
2. Click the Advanced tab, and select the secure hash algorithm, SHA-1.
3. Click OK.
Configuring claim rule

Configure the claim rules for the relying party.
1. On AD FS 2.0, select rsso-sp, and click Edit Claim Rules from the Actions menu.
2. To add the claim rule, click Add Rule.
a. Select the claim-rule template Send Claims Using Custom Rule.
b. Enter the claim-rule name Send Claims Using UPN. In this case, use the following
script:
Note

The properties "http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties

/format" must be the same as the NameID format value in the Authentication tab
of BMC Remedy Single Sign-On. For example, a Transient Identifier such as urn:
oasis:tc:SAM:2.0:nameid-format:transient.
The FQDN specified for the properties "http://schemas.xmlsoap.org/ws/2005/05
/identity/claimproperties/namequalifier" must be the FQDN of the Active Directory
server.
The properties ""http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties
/spnamequalifier" must be the same as the SP Entity Id value specified in BMC
Remedy Single Sign-On (General > Advanced > SAML Service Provider > SP
Entity ID).
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"
]
=> issue(Type =
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" ,
Issuer = c.Issuer,
OriginalIssuer = c.OriginalIssuer,
Value = c.Value,
ValueType = c.ValueType,
Properties[ "http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format" ]
= "urn:oasis:names:tc:SAML:2.0:nameid-format:transient" ,
Properties[ "http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties
/namequalifier" ]
= "http://vm-w28-rds123.sso.com/adfs/services/trust" ,
/spnamequalifier" ]
= "rsso-sp" );
Export ADFS certificates
1. Export ADFS certificates as files.

2. a. Open the ADFS 2.0 Management console.
b. From the explorer panel, go to Service > Certificates.
Double click the certificate name.
Select the Details tab.

2.
Click Copy to File and then click Next.

Select Do not export the private key and then click Next.
Select DER and then select the file to save it.
Click Finish.
3. Perform the following steps to import the ADFS certificates into BMC Single Sign-On cot.jks
with KeyStore Explorer tool:
<tomcat>/webapps/rsso/WEB-INF/classes/cot.jks
a. Open the truststore file using the KeyStore Explorer.
b. Select Tools and click Import Trusted Certificate.
c. Select the file and import it.
4. Restart the BMC Remedy Single Sign-On server.
Using Kerberos for Authentication

Kerberos is a network authentication protocol that is designed to provide strong authentication for
client/server applications by using strong cryptography. Such authentication enables a client to
prove its identity to a server (and vice versa) across an insecure network connection.
The following table briefly outlines the steps to configure BMC Remedy Single Sign-On for
Kerberos authentication.
1. Configuring a To enable Kerberos authentication, you need to set up a server. This server is called a Key
Domain Controller Distribution Center (KDC) which manages the Kerberos protocol.
(see page 665)
In this instance, a domain controller is configured as a KDC.
2. Configuring In the BMC Remedy Single Sign-On Admin console, the process for Kerberos authentication is the
Kerberos for same as SAML. But the differentiation in terms of implementing the Kerberos protocol happens at
authentication (see the domain controller (Key Distribution Center) and the ADFS (Identity Provider) ends.
page 667)
3. Configuring ADFS After you configure BMC Remedy Single Sign-On as the local service provider and ADFS as the
for Kerberos remote identity provider in the BMC Remedy Single Sign-On Admin Console, you must configure
authentication (see ADFS to handle the Kerberos protocol.
page 669)
4. Reconfiguring your As a final step, you need to reconfigure your browser to handle the Kerberos authentication
browser (see page process.
673)

Related topics
Orientation
Security concepts
Configuring Domain Controller

To enable Kerberos authentication, you need to set up a server. This server is called a Key
Distribution Center (KDC) and manages the Kerberos protocol. The protocol involves creating the
user's details in the Active Directory and generating a keytab file.
In this instance, a domain controller is configured as a KDC to handle the following functions.
Create user's details in Active Directory (see page 665)

Generate a keytab file (see page 665)
Add more SPN to the user (see page 666)
Create user's details in Active Directory
1. Specify the first name and user logon name.

2. Specify the new user’s password and verify that the User cannot change password and
Password never expires check boxes are selected.
3. Click Finish.
Generate a keytab file

A keytab file is used to hold the Service Principle Name (SPN) credentials for the BMC Remedy
Single Sign-On to communicate with the domain controller. This service principal is used by clients
to request a service ticket during the authentication process.
Use the ktpass command-line utility to export the keytab file using the command line shown below.
Run this utility in a directory suitable for writing a file with sensitive data. This command will
automatically assign HTTP/<host> SPN to the user.

ktpass /out <file> /mapuser <user> /princ HTTP/<host>@<DOMAIN>

/pass <password> /ptype KRB5_NT_PRINCIPAL/Target<DOMAIN>/kvno 0
Where:
<file> - is the name of the keytab file that you are generating
<user> - user logon name of the user you have created on the previous step
<password> - is the password of the user you have created on the previous step
<host> - is the fully qualified domain name of the host on which BMC Remedy Single Sign-
On server runs including the internet domain
<DOMAIN> - is the Active Directory domain name written in uppercase.
Example:
ktpass /out c:\remedyssoservice.keytab /mapuser remedyssoservice

/princ HTTP/kbp1-dhp-f53342.example.com @RSSO .com
/pass RemedySs0service /ptype KRB5_NT_PRINCIPAL /Target RSSO.com /kvno 0
Warning
A Kerberos authentication issue can arise if the keytab file was generated with
incompatible KVNO number. For more information, refer the section "Invalid keytab index
number for Kerberos authentication" in the Troubleshooting authentication issues (see
page 4773) topic.
Add more SPN to the user

You may assign one more SPN to the user with the command
setspn -S HTTP/<machine_name> <user>
Where:
• <machine_name> - is the name of the computer on which BMC Remedy Single Sign-On server
runs (internet domain is not included).
• <user> - user logon name of the user created in the previous step.

Example:
setspn -S HTTP/kbp1-dhp-f53342 remedyssoservice
Configuring Kerberos for Authentication

In the BMC Remedy Single Sign-On Admin console, the process for Kerberos authentication is the
same as SAML. But the differentiation in terms of implementing the Kerberos protocol happens at
the domain controller (Key Distribution Center) and the ADFS (Identity Provider) ends.
To configure Kerberos for authentication

2. Click General.
/Menu
Basic tab
time
Log Server Log Select the level of log details to be displayed from the drop-down list. The options are:
Level ERROR
WARN
INFO
DEBUG
TRACE
Advanced tab
Cookie


/Menu
Cookie The cookie name is automatically created at installation and based on the timestamp.
installation.

Secured
Cookie
Provider
URL
Certificate
4. Click Realm.
5. In the Realm list window, edit an existing realm or create a new realm by entering the
following details.
General tab
Field Description
/Menu
Realm Example: Yourcompany.

ID
Realm Host name of an external application (for example, BMC Remedy Mid Tier or BMC MyIT) that is integrated
Domain with BMC Remedy Single Sign-On. The realm name is automatically defined by the domain name. Separate
(s) multiple names using commas.
Examples: firstcompany.midtier.bmc.com, secondcompany.midtier.bmc.com, thirdcompany.midtier.bmc.com
Final Enter the URL to which the user will be directed after logging out.
Logout
URL
Authentication tab
Field/Menu Description
Authentication Select the SAML option.

Type
Identity Click the Import button to populate the fields with relevant data from the IdP. You may also enter the
Provider data in the fields manually.
IdP Entity ID Obtained from an external IdP provider such as ADFS or Okta.
Examples:http://adfs.local/adfs/services/trust, http://www.okta.com/exk4mi22tbfhiAnIn0h7
Login URL Obtained from an external IdP provider such as ADFS or Okta.
Examples:https://adfs.local/adfs/ls, https://dev-726770.oktapreview.com/app
/bmcdev726770_oktaidp_1/exk4mi22tbfhiAnIn0h7/sso/saml
Sign Request If the IdP requires that the authentication request be signed, select this option.

Field/Menu Description
Sign If BMC Remedy Single Sign-On requires a signed response from the IdP, select this option.
Response BMC Remedy Single Sign-On validates the signature from the authentication response.
Compress To compress the SAML message to save space in the URL, select this option.
Request
User ID Enter the user ID attribute.

Attribute
Transformation Select an option (RemoveBMCDomain, RemoveEMailDomain, TO_UPPER_CASE,

TO_LOWER_CASE) from the drop-down list.
NameID Select an option from the drop-down list.

format Defines the name identifier formats supported by the service provider. Name identifiers are a way for
providers to communicate with each other regarding a user.
The Name ID format list is an ordered list, the first Name ID has the highest priority in determining the
Name ID format to use. If the user does not specify a Name ID to use when initiating single sign-on,
the first one in this list is chosen and supported by the remote Identity Provider.
A persistent identifier is saved to a particular user's data store entry as the value of two attributes. A
transient identifier is temporary and no data will be written to the user's persistent data store.
Auth Context Select an option (exact, minimum, maximum, better) from the drop-down list.
Compare
Auth Context Enter the authentication context.

This attribute maps the SAMLv2-defined authentication context classes to the authentication level set
for the user session for the service provider.
Auth Issuer Enter the SP Entity ID.
Force Select the check box to enforce the authentication.

Authentication
Service To view data, click the View Metadata button.

Provider
Template Authentication Request Template - Select Default or Custom to edit the template used for
SAML authentication request.
SP Metadata Template - Select Default or Custom to edit the service provider metadata
template. This metadata is generated when you click the View Metadata button against Service
Provider.
Configuring ADFS for Kerberos Authentication

After you configure BMC Remedy Single Sign-On as the local service provider and AD FS as the
remote identity provider in the BMC Remedy Single Sign-On Admin Console, you must configure
AD FS to handle the Kerberos protocol.
You must perform the following activities to configure ADFS.

Import Certificates (see page 670)

Configure Relying Party Trust (see page 671)
Modifying the secure hash algorithm (see page 672)
Configuring claim rule (see page 672)
Export ADFS certificates (see page 673)
Import Certificates
To import certificates
1. Go to the AD FS server
2. Import the following certificates via the mmc console to Trusted Root CA:
SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On is deployed
Click here to read the steps to import the certificates.
a. From the Run dialog box, type mmc to open Microsoft Management Console
(MMC).
b. Open the File menu and click Add/Remove Snap-in…
c. Select Certificates from the list of available snap-ins and click Add.
The Certificates snap-in dialog box is displayed.
d. Select My User Account, and click Finish and OK.
e. Open Personal>Certificates from the explorer panel.
f. On the Action menu, point to All Tasks, and then click Import to start the Certificate
Import Wizard.
g. Import the SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On
is deployed and the Signing certificate.
h. Open Trusted Root Certification Authorities>Certificates from the explorer panel.
i. Import the SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On
is deployed.
SSL certificate of the Tomcat on which the BMC Remedy Single Sign-On is
deployed.
Click here to expand to read the steps to export the certificate.
a. When you open the BMC Remedy Single Sign-On URL, click on the padlock
symbol in the address line of the browser.
b. In the Certificate window, click on the Details tab.
c. Click Copy to File.
d. In the Certificate Export Wizard, click Next.
e. In the displayed page, select "DER encoded binary X.509 (.CER)".
f. Click Next.
g. Provide a name for the file and include the path in the file name.
Note

Note: The Common Name (CN) attribute of this certificate must be the same
as the FQDN of the BMC Remedy Single Sign-On server.
Signing certificate (optional) - The certificate (webapps/rsso/WEB-INF/classes/cot.

jks) that will be used to sign the specified SAML messages. This certificate is
available in the Admin UI (General > Advanced > SAML Service Provider > Signing
Certificate) of BMC Remedy Single Sign-On.
Configure Relying Party Trust
1. On the AD FS server, open the AD FS 2.0 Management application.

2. On Trust Relationships tab, click Relying Party Trusts.
3. Click Add Relying Party Trust. A wizard appears.
4. Configure the following parameters:
a. Select Import data about the relying party published online or on a local network
.
b. Copy the metadata web link that you received from the BMC Remedy Single Sign-
On. For example, https://rssoexample.bmc.com:8443/rsso/getmetadata.jsp?
tenantName=<name of the corresponding tenant>.
Note
If you see a warning, you can ignore it. However, if you are unable to
proceed with the configuration, the certificates were not exchanged
correctly. Contact the BMC Remedy Single Sign-On administrator for more
information.
In case of specific network settings when AD FS and BMC Remedy Single
Sign-On servers are not able to connect using SSL protocol, this error
message may be normal and can be ignored. In this case, you can import
the SP metadata into AD FS offline using an XML file.
c. Click Next.
d. Type rsso-sp for the display name, and click Next.
e. Select ADFS 2.0 profile, and click Next.
f. Select Permit all users to access this relying party, and click Next.
g. Clear the Open the Claims when this finishes check box.
h. Click Close.
After closing the Add Relying Party Trust Wizard window, sp appears in the Relying Party Trusts
list.

Modifying the secure hash algorithm
1. Right-click rsso-sp, and select properties.

The rsso-sp Properties dialog box appears.
2. Click the Advanced tab, and select the secure hash algorithm, SHA-1.
3. Click OK.
Configuring claim rule

Configure the claim rules for the relying party.
1. On AD FS 2.0, select rsso-sp, and click Edit Claim Rules from the Actions menu.
2. To add the claim rule, click Add Rule.
a. Select the claim-rule template Send Claims Using Custom Rule.
b. Enter the claim-rule name Send Claims Using UPN. In this case, use the following
script:
Note
The properties "http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties

/format" must be the same as the NameID format value in the Authentication tab
of BMC Remedy Single Sign-On. For example, a Transient Identifier such as urn:
oasis:tc:SAM:2.0:nameid-format:transient.
The FQDN specified for the properties "http://schemas.xmlsoap.org/ws/2005/05
/identity/claimproperties/namequalifier" must be the FQDN of the Active Directory
server.
The properties ""http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties
/spnamequalifier" must be the same as the SP Entity Id value specified in BMC
Remedy Single Sign-On (General > Advanced > SAML Service Provider > SP
Entity ID).
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"
]
=> issue(Type =
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" ,
Issuer = c.Issuer,
OriginalIssuer = c.OriginalIssuer,
Value = c.Value,

ValueType = c.ValueType,
Properties[ "http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format" ]
= "urn:oasis:names:tc:SAML:2.0:nameid-format:transient" ,
/namequalifier" ]
= "http://vm-w28-rds123.sso.com/adfs/services/trust" ,
/spnamequalifier" ]
= "rsso-sp" );
Export ADFS certificates
1. Export ADFS certificates as files.

2. a. Open the ADFS 2.0 Management console.
b. From the explorer panel, go to Service > Certificates.
Double click the certificate name.
Select the Details tab.
Click Copy to File and then click Next.
Select Do not export the private key and then click Next.
Select DER and then select the file to save it.
Click Finish.
3. Perform the following steps to import the ADFS certificates into BMC Single Sign-On cot.jks
with KeyStore Explorer tool:
<tomcat>/webapps/rsso/WEB-INF/classes/cot.jks
a. Open the truststore file using the KeyStore Explorer.
b. Select Tools and click Import Trusted Certificate.
c. Select the file and import it.
4. Restart the BMC Remedy Single Sign-On server.
Reconfiguring your browser

This topic provides instructions for reconfiguring your browser to handle the Kerberos
authentication process.

Note
You cannot use the browser on the same computer as BMC Remedy Single Sign-On
server.
Configure user's browser

For Internet Explorer
1. Navigate to Tools > Internet Options > Advanced.

2. On the Advanced tab and in the Security section, select Enable Integrated Windows
Authentication (requires restart).
3. On the Security tab, select Local Intranet.
4. Click Custom Level.
5. In the User Authentication/Logon section, select Automatic logon only in Intranet zone.
6. Click OK.
7. Click Sites and select all the options (default).
8. From the Sites popup, click Advanced and add the BMC Remedy Single Sign-On service
web site to the local zone (the website might be already added). For example, sample.bmc.
com.
9. Click Add.
10. Click OK for all the pop-ups.
For Mozilla Firefox
1. Enter the following URL: about:config.

2. Click I'll be careful, I promise!
3. Double click the Preference Name: network.negotiate-auth.trusted-uris.
4. Add the Fully Qualified Domain Name (FQDN) of the host, for example, sample.bmc.com.
5. Double click the Preference Name: network.automatic-ntlm-auth.trusted-uris
6. Add the Fully Qualified Domain Name (FQDN) of the host, for example, sample.bmc.com.
7. Click OK.

Using LDAP for authentication

You may enable LDAP for single sign-on user authentication. On configuring LDAP authentication
for a particular realm, the id and password entered by the user are validated against the id and
password stored in the LDAP directory.
To configure LDAP for authentication

2. From the menu, click Realm.
3. Click Add Realm.
To edit an existing realm, from the List of Realms, click Edit Realm against the
realm.
4. Under Authentication, select LDAP as the Authentication Type.

5. Enter the following details.
Field Description
Server Host Enter the host's Fully Qualified Domain Name (FQDN) for the LDAP server.
Server Port Specify the port number for the LDAP server.
Use TLS Enable to use TLS to connect to the LDAP server. In addition, before communications can be
connection established, the certificates for the LDAP server must be imported to the trust store of Apache Tomcat
used by BMC Remedy Single Sign-On. For example, <TOMCAT_HOME>/config/cacerts, where
'cacerts' is the truststore file.
You may use the KeyStore Explorer to import the certificates.
Bind DN Type the distinguished name of an LDAP user. For example, cn=rsso-user, cn=Users, dc=example,
dc=com.
This is the administrator bind distinguished name for querying LDAP and hence this user must have
priveleges to search the directory.
Bind Password Enter the password for LDAP user with the administrator bind distinguished name.
Base DN for Starting location within the LDAP directory for performing user and group searches. The search DNs
user search should be as specific as possible for performance reasons. The depth of the search that is performed
can be configured. If an object search is specified, then the DN should be the DN of the node
containing the users.
Identity Add the user attribute names on which to perform the search to the attribute list.
Attributes
Search Scope Select one of the options (Object, One Level, Subtree) to provide the scope for search.
Transformation Select an option (None, RemoveBMCDomain, RemoveEmailDomain, ToLowerCase, ToUpperCase)

from the drop-down list.
Note

Click Test to verify the LDAP connection.
Related topics
Orientation
Security concepts
Managing Server Configuration

BMC Remedy Single Sign-On allows you to configure server details such as cookie name, cookie
domain, session settings, log details, and SAML service provider details. You can also export or
import the configuration details of the server.
Edit Server Parameters (see page 676)

Export Server Configuration details (see page 677)
Import Server Configuration details (see page 677)
Edit Server Parameters

To edit server parameters

2. Click General.
Field Description Description
Basic tab
This cookie domain must be the same for both BMC Remedy Single Sign-On server and its
integrated application server.
time
Log Select the level of log details to be displayed from the drop-down list. The options are:

Field Description Description
Server Log ERROR

Level WARN
INFO
DEBUG
TRACE
Advanced tab
Cookie Cookie The cookie name is automatically created at installation and based on the timestamp.
installation.

Secured
Cookie
Provider
URL
Certificate
4. Click Save.
Export Server Configuration details

To export configuration details
From the Admin menu, click Export.

The server configuration details including the templates will be exported. In most
browsers, a file will be downloaded to your local machine automatically. But In Safari,
a new browser with the exported configuration will be opened. You can copy and
save the content.
Import Server Configuration details

To restore previously exported configuration information, you have to use import.
To import server configuration details
1. From the Admin menu, click Import.

2. Browse to select the required file.
After the file is imported, Admin UI will be refreshed to display the imported
configuration

Related topics
Using BMC Remedy AR System for Authentication

Using SAML for Authentication
Using Kerberos for Authentication (see page 664)
Using LDAP for authentication (see page 675)
Securing BMC Remedy AR System

The following topics provide information about how to secure BMC Remedy AR System:
Configuring SSL for the email engine (see page 678)

Resetting the Application Service password (see page 684)
Securing incoming and outgoing email (see page 684)
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 (see page 681).
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 (see page
682).
c.
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
(see page 682).
3. Make sure that email users obtain their own certificate.
a. Through the CA, generate a personal certificate that users will use for signing and
encrypting their email messages. With a local CA, you can retrieve and install the cert
using a browser.
Selecting a cert to use with your IMAP account
b. In the email client, open the Properties dialog for your IMAP account and select the
new cert to use for signing and encrypting email messages.
Two users who have properly configured the certs on their mail client must then
exchange certificates so that their communications can be secured.
c. Send email messages that are signed, but not encrypted, between the two users.
A signed email message

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.
d. On the Organization Information page, select an Organization and the

Organizational unit, and click Next.
e. On the Your Site's Common Name page, enter the common name for your site.
You can access the Microsoft Exchange server with this common name. This name
will also be used to configure SSL on Outlook Express.
Do not enter an IP address as the common name, otherwise the CA would create the
SSL certificate successfully.
f. On the Geographical Information page, select the appropriate Country/Region,
State/province, and City/locality, and click Next.
g. One the Certificate Request File Name page, enter the absolute path and file name
for the CSR (for example, certreq.txt ), and click Next.
Make sure that you provide a location that is easy to remember and access.
h. 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.
3.
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/trialcainstall.html.
Follow the prompts on the screen and install the test root CA on the computer where you
want to configure Outlook Express.
When prompted to enter the IMAP server address, you must provide the "common name"
you entered while creating the CSR. If you provide any other value or an IP address, the
"CN does not match with passed value" warning appears.
2. To configure Email Engine to use SSL, import the test root CA certificate in keystore by
using following command:
<javaHome>\bin\keytool - import -alias "testroot"

-keystore <javaHome>\lib\security\cacerts
-file <certFilePath>/testroot.cer
javaHome is the directory where JRE (not JDK) is installed.
Note
Find the appropriate keystore path before entering the command. Email Engine uses the
location where Oracle Java Runtime Environment (Oracle JRE) is installed as the
keystore path.

Resetting the Application Service password

If you change the Application Service password on the AR System Administration: Server
Information form after you install Flashboards, you must run the Flashboards driver to reset the
password before running the BMC Remedy Flashboards server again. If you do not reset the
password, the BMC Remedy Flashboards server will not be able to log onto the BMC Remedy AR
System server.
Note
To avoid authentication failures, passwords for BMC Remedy AR System applications

must not exceed 20 characters.
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.
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 (see page 685)
Configuring BMC Remedy Email Engine for replying with results (see page 686)
Configuring incoming mailbox security (see page 687)
Configuring outgoing mailbox security (see page 688)
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.
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
(see page ).
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
10. Set the Delete Outgoing Notification Messages field to No.
11. Open the AR System Email Security form in New mode.
12. Create a user record as follows:
a. Set Status to Enabled.
b. Create a security key.
c. Make sure that the Force For Mailbox field is set to No (default).
d. Select either Yes or No for the Force From Email Address.
This field enforces the email address that is associated with the key to be used. If set
to Yes, the From Address of the reply sent by the user is checked against the
security key entry's From Address.
e. Enter other information as needed, for example, an expiration date.
Note
A user making modifications must have a write license unless that user is
the submitter or the Submitter Mode is set to Locked.
Configuring BMC Remedy Email Engine for replying with results

When you set the Reply with Result and Reply with Entry fields on the AR System Email
Mailbox Configuration form to Yes, the Email Engine sends reply email back to the sender. The
email contains the information that was submitted, queried, or modified on the form.

To configure the Email Engine for replying with results
1. In a browser, open the AR System Email Mailbox Configuration form in Search mode.
2. Search for and open the records for your incoming and outgoing mailboxes.
3. Make sure that you have an incoming mailbox and an outgoing mailbox associated with
each other.
4. Click the Advanced Configuration tab of the outgoing mailbox.
5. (Recommended for testing purposes) Set the Delete Outgoing Notification Messages
field to No.
7. Click the Advanced Configuration tab of the incoming mailbox from which you want the
8. Set the following fields as indicated:
Email Action: Parse
Use Original Template Format: No
Reply With Result: Yes
Reply With Entry: Yes
Enable Modify Actions: No
Force Default Workflow Form: No
9. Set one of the following fields to Yes:
Use Security Key
Use Supplied User Information
Use Email From Address
Configuring incoming mailbox security

Security keys associated with an incoming mailbox validate the permissions for incoming emails to
perform various actions on the AR System server, such as modifying entries. In the AR System
Email Mailbox Configuration form, you specify whether a security key is required for email sent to a
mailbox (see Configuring advanced incoming mailbox properties (see page )). 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.

2.
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.
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:
Note
Do not use the AR System Configuration Component Setting form to configure

encryption.
Encryption tab
The Encryption tab contains the following information:
Encryption Level Available — The type of encryption installed on the server:

Standard — Standard security

Performance — BMC Remedy Encryption Performance Security

Premium — BMC Remedy Encryption Premium Security
Note
The available level of encryption is displayed in this field whether encryption

is activated or not.
Active Encryption Settings — The server's current encryption configuration.

Changes applied to the New Encryption Settings box do not appear in these read-only fields
until the server is restarted.
New Encryption Settings — Fields in which you can change the server's encryption
configuration.
When you change these settings and click Apply, the changes are saved in the AR System
server configuration file (ar.cfg on Windows; ar.conf on UNIX). They do not take effect or
appear in the Active Encryption Settings box, however, until the server is restarted.
The following topics provide detailed information about configuring encryption security:
Configuring the data key (see page 690)

Configuring the public key (see page 692)
Activating encryption (see page 693)
Deactivating encryption (see page 694)
Activating FIPS compliance (see page 695)
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.
3. Click System > General > Server Information.
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-bit RC4 key.

128 Available for Performance Security that does not comply with FIPS. Encrypt-Data-
RC4- 2048-bit RC4 key.

2048 Available for Premium Security that does not comply with FIPS. Encrypt-Data-
AES- 128-bit AES CBC key. FIPS noncompliant:

128 Required for Performance Security that complies with FIPS,
but can be used by servers that do not comply with FIPS. Encrypt-Data-
For more FIPS information, see FIPS encryption options in BMC Remedy
ITSM Deployment documentation.
FIPS compliant:
Encrypt-Data-
AES- 256-bit AES CBC key. FIPS noncompliant:

256 Required for Premium Security that complies with FIPS,
but can be used by servers that do not comply with FIPS. Encrypt-Data-
For more FIPS information, see FIPS encryption options in BMC Remedy
ITSM Deployment documentation.
FIPS compliant:
Encrypt-Data-
Note
The available algorithms depend on the type of encryption installed and the setting
of the FIPS Enabled option.
6. (Optional) In the Key Expire Interval field, specify a different life span for the key in
seconds.
The default is 2700 seconds (45 minutes). At the end of the specified time, the key expires,
and a new key exchange occurs.
Note
Generating keys more frequently provides higher security at some marginal impact
to performance.

In the AR System server configuration file, this setting is specified as follows:
Encrypt-Symmetric-Data-Key-Expire: 2700
7. Click Apply.
9. Relog on to any clients that are connected to the server.
Configuring the public key

BMC Remedy Encryption Performance Security and BMC Remedy Encryption Premium Security
use the RSA algorithm for public key cryptography to exchange private keys. This key exchange
occurs at the beginning of the API session and when the data encryption keys expire.
If the server's security policy is changed while a client is running, the client connections using the
old policy automatically perform a key exchange to create keys that correspond to the new policy.
To configure the cryptograhic algorithm and size of the public key

5. In the New Encryption Settings: Public Key Details area, select one of these data
encryption algorithm options:
Option Description Server configuration file
setting
RSA 512 512-bit RSA key. Default for standard security.
Encrypt-Public-Key-
Algorithm: 4
RSA 1024-bit RSA key. Default for BMC Remedy Encryption Performance
1024 Security.
Encrypt-Public-Key-
Algorithm: 5
RSA 2048-bit RSA key. Default for BMC Remedy Encryption Premium
2048 Security.
Encrypt-Public-Key-
Algorithm: 6

Note
The available algorithms depend on the type of encryption installed and the setting
of the FIPS Enabled option.
6. (Optional) In the Key Expire Interval field, specify a different life span for the key in
seconds.
The default is 86400 seconds (24 hours). At the end of the specified time, the key expires,
and the server generates a new key.
Note
Generating keys more frequently provides higher security at some marginal impact
to performance.
In the AR System server configuration file, this setting is specified as follows:
*Encrypt-Public-Key-Expire: 86400*
7. Click Apply.
Activating encryption
The Security Policy value in the Encryption tab (see Encryption tab (see page 689)) 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
state configuration
file setting
Activated Optional This is the default for BMC Remedy Encryption Performance Security and Encrypt-
BMC Remedy Encryption Premium Security FIPS noncompliance. Security-
Clients with and without encryption installed can communicate with the Policy: 0

Encryption Value Description Server

state configuration
file setting
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 Encrypt-
BMC Remedy Encryption Premium Security FIPS compliance. Security-
Only clients with encryption installed can communicate with the server. Policy: 1
Note
The encryption level installed on the client (standard, BMC

Remedy Encryption Performance Encryption, or BMC Remedy
Encryption Premium Encryption) must be compatible with the
encryption algorithms used by the server.
Deactivated Disabled This is the default for standard encryption. Encrypt-

Whether encryption is installed on a client or not, communication with the Security-
server is not encrypted. Network traffic is exchanged in plain text. Policy: 2
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
(see page 690).
7. (Optional) In the Public Key Details area, change the defaults. See Configuring the public
key (see page 692).
8. (Optional) Activate FIPS compliance. See Configuring the data key (see page 690).
9. Click Apply.
Deactivating encryption
To deactivate encryption, select the deactivation options according to the procedure in To activate
or deactivate encryption (see page 693).

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 (see page 689)) in conjunction with the Security Policy setting to switch
compliance with Federal Information Processing Standard (FIPS) 140-2 on or off:
FIPS Security Policy Is server FIPS Description

Enabled value compliant?
option
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, No Clients communicating with the server cannot communicate with
or Disabled FIPS-compliant servers.
For an overview of FIPS, see FIPS encryption options in BMC Remedy ITSM Deployment
documentation.
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 in BMC Remedy ITSM
2. Log on to the server.

6. In the New Encryption Settings area, select the FIPS Enabled option.
7. In the Security Policy list, select Required.
8. In the Data Key Details area, select an AES algorithm.
See Configuring the data key (see page ).
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 (see page ).
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.
14. In the following entry, set integer to 8 (Performance Security) or 9 (Premium Security):
<dataEncryptionAlg> integer</dataEncryptionAlg>
15. In the following entry, ensure that integer is set to 1 (Required).
<encryptionPolicy> integer</encryptionPolicy>
16. Save the configuration file.
17. Restart the Java plug-in server.
Using Oracle CLOBs with BMC Remedy AR

System
This section evaluates the storage and performance impacts of using in-row versus out-row
storage for large objects (LOBs) in a database table in BMC Remedy AR System.
The following topics provide information and instructions:
About Oracle LOBs (see page 697)

Storage size impact (see page 698)
Performance impact (see page 700)
Converting LOB storage (see page 701)
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.
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 44,105,728 94,371,840

rows bytes 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 178,257,920 178,257,920

rows bytes 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 3,211,264 94,371,840

rows bytes bytes
In this case, the out-row space usage is significantly higher than the in-row space usage. The out-
row option uses more space for small data sizes.

Performance impact
When values are greater than 4000 characters, in-row and out-row storage space usage is
equivalent. However, response time performance might be better when the in-row option is used.
The BMC Incident Management application contains a few character large object (CLOB) fields.
One such visible field is the detailed description field in the Incident form. A small load test of 60
users was run with each user creating an incident ticket repeatedly for one half hour. The average
mid-tier response time was recorded when the database was configured for outrow and in-row
storage. The following table shows that the mid tier performs better with the inrow option, whether
the number of characters is greater than or less than 4000.
Response times for creating incidents
Create incident test In- Out-

row row
Description field value < 4000 0.43 s 0.73 s

characters
Description field value > 4000 0.56 s 0.72 s

characters
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.
Converting LOB storage

If your BMC Remedy AR System is currently using out-row storage, you can convert it to use in-
row storage, and vice versa. The following Oracle PL/SQL procedure changes the in-row or out-
row option of all the large object (LOB) columns in an Oracle schema.
The following case studies describe how to convert LOB storage:
Case 1 - Applying changes to all LOBs (see page 704)

Case 2 - Applying changes to LOBs only in a specified table (see page 705)
Case 3 - Displaying SQL statements only (see page 705)
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',

2.
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 <>'L
OB'
)
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 exec p_change_LOB_storage(p_in_row =>'Yes',
in tablespace ARSYSTEM. p_dest_tablespace =>'ARSYSTEM');
Change all LOBs from out-row to in-row, and move them exec p_change_LOB_storage(p_in_row =>'Yes',
to tablespace AR_LOB. p_dest_tablespace =>'AR_LOB');
Move LOBs to tablespace AR_LOB without changing exec p_change_LOB_storage(p_in_row =>Null,

the storage option. p_dest_tablespace =>'AR_LOB');
Change all LOBs from in-row to out-row, and keep them exec p_change_LOB_storage(p_in_row =>'No',
in tablespace ARSYSTEM. p_dest_tablespace =>'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- exec p_change_LOB_storage(p_in_row =>'Yes',
row, and keep them in tablespace ARSYSTEM. p_dest_tablespace =>'ARSYSTEM', p_table_name
=>'T1866');
Change the LOBs in table T1866 from out-row to in- exec p_change_LOB_storage(p_in_row =>'Yes',
row, and move them to tablespace AR_LOB. p_dest_tablespace =>'AR_LOB', p_table_name =>'T1866');
Move LOBs in table T1866 to tablespace AR_LOB exec p_change_LOB_storage(p_in_row =>Null,

without changing the storage option. p_dest_tablespace =>'AR_LOB', p_table_name =>'T1866');
Change LOBs in table T1866 from in-row to out-row, exec p_change_LOB_storage(p_in_row =>'No',
and keep them in tablespace ARSYSTEM. p_dest_tablespace =>'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 Set serveroutput on
execute to change the LOBs in table T1866 from out-row exec p_change_LOB_storage(p_in_row =>'Yes',
to in-row. p_dest_tablespace =>'ARSYSTEM', p_table_name
=>'T1866', p_generate_SQL_only='Yes');
Display the SQL statements that the stored procedure will Set serveroutput on
execute to change all LOBs from out-row to in-row and exec p_change_LOB_storage(p_in_row =>'Yes',
move them to tablespace AR_LOB. p_dest_tablespace =>'AR_LOB',
p_generate_SQL_only='Yes');

Monitoring API calls

As BMC Remedy administrator, you can monitor the AR System server API calls by configuring
certain fields in the AR System Server Information — Advanced tab. You can monitor the API
calls between an AR System server and its clients and capture the following information, which is
recorded in the AR System API Statistics form:
The default value being 0 seconds, the AR System API Statistics form is updated
immediately after the fields are configured.
Number of API calls by client type (for example, mid tier or BMC Remedy Developer Studio)
Total amount of data sent to the client as a result of the API calls
Total amount of data sent by the client to the server as a request
Number of successful API calls
Number of failed API calls
IP address of the client from where the call was initiated
IP address of the server that responded to the request
To monitor API calls

Server Information.
3. In the API Recording Client Types field, enter the client types for which you want to
monitor API calls.
By default, calls from all client types are monitored. Specify values separated by semicolons
in the following format: clientType;IPAddressExpression;clientType;IPAddressExpression.
For more information, see Setting performance and security options (see page 285).
4. In the Enable API Recording field, select whether you want to enable the system for
monitoring API calls.
By default, monitoring is disabled. Selecting Yes in this field indicates that you have enabled
the system for monitoring.
For more information, see Setting performance and security options (see page 285).
5. Save the changes.
To view API call details

Open the AR System API Statistics form by typing the URL in a browser in this format: http://
midTier:port/arsys/forms/server/AR+System+API+Statistics.

The AR System API Statistics form displays the following information:
Client type Type of client that initiated an API call (see the following table (see page 707))
Total count Total number of successful and failed calls
Error count Number of unsuccessful calls
Client IP Address IP address of the client making a call
End client IP Address IP address of the client using the mid tier or the web service
Data In Total number of bytes sent as a request from the source IP address
Data Out Total number of bytes sent out as a response to the API call
Start Timestamp Time when the API call monitoring started, specified in hours. The monitoring time frame is 1
hours.
End Timestamp End time of API call monitoring. For example, if the start time is 03:00, the end time will be 04:00.
Server IP address of the computer where the AR System server is running
The following table lists the supported client types and the value associated with each client type.
Client types
Client type Value
Unknown 0
Pre-5.0 AR System clients 1
BMC Remedy Administrator 2
BMC Remedy User 3
BMC Remedy Data Import 4
BMC Remedy Distributed Server Option (DSO) 5
BMC Remedy AR System ODBC 6
BMC Remedy Approval Server 7
AR Web Server 8
BMC Remedy Mid Tier 9
Palm Pilot 10
BMC Remedy Flashboards 11
Flashboards Mid Tier 12
BMC Remedy Enterprise Integration Engine 13
arreload 14
arcache 15
ardist 16

Client type Value
runmacro 17
armail 18
Command-line import tool 19
Report Creator plug-in 20
BMC Remedy Email Engine 22
Debugger 24
Object Store API 25
Object Store Sync Utility 26
Server Administration plug-in 27
BMC Service Impact Management Publishing server 28
BMC Service Impact Management Service Model Editor 29
BMC Atrium CMDB Engine 30
BMC Atrium CMDB Driver 31
BMC Atrium CMDB Reconciliation Engine 32
BMC Remedy Assignment Engine 33
BMC Remedy AR System Web Service 34
Normalization Engine 35
BMC Remedy Developer Studio 36
Full Text Reader 37
BMC Atrium Single Sign-On Server 38
AR Migrator 39
AR UDM Adapter 40
BMC Remedy Knowledge Management Operations plug-in 41
BMC Remedy Knowledge Management Form Permissions plug-in 42
BMC Remedy Knowledge Management Document Migrator plug- 43

in
BMC Remedy Knowledge Management File System plug-in 44
BMC Remedy Knowledge Management File System Sync plug-in 45
BMC Remedy Knowledge Management Group plug-in 46
BMC Remedy Knowledge Management Registration plug-in 47
BMC Asset Management SWLM Rule Engine plug-in 48
BMC Asset Management Software Usage plug-in 49
BMC Asset Management RLE Configuration plug-in 50

Client type Value
BMC Asset Management Charge Back plug-in 51
BMC Remedy IT Service Management (ITSM) Common plug-in 52
BMC Remedy ITSM CAI plug-in 53
BMC Remedy ITSM Utility plug-in 54
BMC Remedy ITSM AppQuery plug-in 55
BMC Remedy ITSM Next ID plug-in 56
BMC Atrium Integrator 57
BMC Atrium Discovery (ADDM) 58
BMC Proactive Performance Management 59
Driver 4000
Dispatcher 4001
arhelp 4002
arjanitor 4003
armenu 4004
arstruct 4005
artext 4006
arsqled 4007
archgsel 4008
archgid 4009
arlabel 4010
BMC Remedy AR System Installer 4011
BMC Remedy Install Kit (RIK) 4012
Reserved range 5000

Upgrading
For the latest installation information, see BMC Remedy ITSM 9.1 Deployment online
documentation (see page 710) .
About BMC Remedy ITSM Suite 9.1

Deployment online documentation
The following graphic illustrates scope and the contents of this online documentation.
The following table describes the contents of the different branches in this online documentation.
Branch Description
Planning the This section describes the deployment scenarios for the following new components:
deployment
Click here for a list of topics in this section
Planning BMC Remedy Smart Reporting deployment

Planning BMC Remedy shared service architecture
Preparing This section provides information about the preparation you must do before installing or upgrading any
component of the BMC Remedy ITSM Suite.
Reviewing system requirements

Downloading the installation files
Obtaining BMC Remedy license keys
Preparing your database
Preparing the base platform
Preupgrade checks and configuration checks

Branch Description
Completing the planning spreadsheet
Installing This section provides information about the steps for performing a fresh installation.
Installing the platform components

Installing the application components
Installing offline documentation
Deploying BMC Remedy shared services
Upgrading This section provides information about the steps for performing an upgrade.
Interactive end-to-end steps depending on the base version:

Upgrading from version 8.1 and later
Upgrading from a version 7.6.04 or 8.0.xx
Upgrading from a version earlier than 7.6.04
Upgrading information the individual components in the BMC Remedy ITSM Suite
Upgrading the platform
Upgrading the applications
Detailed information of different stages within the upgrade process:
Restrictions after restoring the database on the upgrade server
Setting up upgrade servers
Capturing a snapshot of your current environment
Creating overlays
Adjusting customizations when upgrading
Reconciling AR customizations
Migrating customizations
Updating hard-coded server hostname references
Migrating delta data
Update to the multi-tenancy model
Post-upgrade activities
Upgrading secondary servers
User acceptance testing
Cutover activities
Go live activities
Troubleshooting This section provides information about troubleshooting the issues specific to install or upgrade.
Working with logs

Troubleshooting data and workflow import issues
Troubleshooting driver issues
Troubleshooting information for individual components in the BMC Remedy ITSM Suite
Troubleshooting BMC Remedy AR System issues
Troubleshooting BMC Atrium Core issues
Troubleshooting BMC Remedy ITSM issues
Troubleshooting Process Designer issues
Troubleshooting BMC Service Request Management issues
Troubleshooting BMC Service Level Management issues

Branch Description
Troubleshooting the multi-tenancy update

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 Integration

method, and a technology method considerations (see
page 714)
Extending AR System server functionality to external data by Enabling Plug-ins

using installed and created plug-ins (see page 719)
Configuring and using the ARDBC and AREA LDAP plug-ins to Integrating with a
integrate BMC Remedy AR System with a directory service directory service (see
page 789)
Using plug-ins and the AREA API to integrate BMC Remedy AR AR System external
System with external user authentication services authentication (see
page 828)
Viewing and processing external data, accessing external Data and database
relational database tables, reading data from the AR System integrations (see
database with a third-party application, and providing read-only page 838)
access to data in BMC Remedy AR System forms
Creating custom plug-ins for BMC Remedy Developer Studio Extending BMC
Remedy Developer
Studio (see page 862)
Automating tasks and processes by integrating BMC Remedy BMC Atrium

AR System with BMC Atrium Orchestrator Orchestrator
integration (see page
867)
Executing and controlling external applications within workflow Running external

to supplement AR System servers and clients processes with the
Run Process action
(see page 876)
Automatically specifying the person responsible for handling a Integrating the BMC
request in an application Remedy Assignment
Engine into an
application (see page
885)

Integration considerations
Special mechanisms can be used to integrate BMC Remedy AR System with another application.
This section discusses the issues to consider when planning an integration.
This section contains information about:
Where to integrate BMC Remedy AR System (see page 714)

Multiplatform issues (see page 716)
Choosing an implementation method (see page 716)
Integration technologies (see page 717)
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 (see page 714)

Integrating the AR System server (see page 715)
Integrating the database (see page 715)
Integrating the mid tier (see page 715)
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 (see page 713)section.
Multiplatform issues
A major consideration for every integration implementation is the range of platforms that are
involved.
BMC Remedy AR System clients are available for Windows and on all major platforms through the
Web using the mid tier. In some cases, integration at the client level is unique for the different
platforms.
The BMC Remedy AR System workflow qualifications include functions to test for the different
platforms.
Multiple workflow definitions can be triggered in parallel, and the one appropriate for the platform is
executed. In some cases, you can avoid the client functionality issue by running a process on the
server from client workflow. Because the application executes on the AR System server's platform
and operating system, it does not matter which client platform triggered the workflow.
Similarly, different AR System server platforms might require adjustments to integration

implementations.
Choosing an implementation method

The following section outlines some methods by which you can implement integration with BMC
Remedy AR System.
How quickly do you want to have the integration working?

Some options are easy to get running for demonstration purposes, but have drawbacks for
production deployment. The more complex the integration, the more time is required to
implement it.
How "robust" does the integration need to be? How heavy will the usage be, and are there
any data throughput requirements?
For an integration that will be used infrequently, some of the methods are simple to
implement. If the integration involves moving a large amount of information, other methods
might require more effort but produce better results.
Will users be able to modify the integration? How will it be supported?

Some of the methods do not lend themselves to user modification. Others are easily
modifiable, but might be more difficult to support if changes are made.

Integration technologies
A basic design philosophy of BMC Remedy AR System is that it is almost always used in
conjunction with other tools and products to create an integrated solution. BMC Remedy AR
System is designed to have many integration points, making it easy to combine with your other
solutions.
This table lists the technologies available for integrating with BMC Remedy AR System:
Method Description Section or topic
REST API The API is a web service that conforms to the architectural principles of BMC Remedy AR
Representational State Transfer (REST). The REST API is a simple stateless System REST API
architecture that runs over the HTTP. overview (see page 3535
).
C API The AR System API on the server is the most technically complex method. It BMC Remedy AR
(Application requires knowledge of C programming and building executables. However, it System C API overview
Programming provides access to all AR System server functionality for tightly linked, high- (see page 3568)
Interface) performance integration.
Java API The AR System Java API is a collection of Java classes that provide AR System C BMC Remedy AR
API functionality in a Java development environment. Using this abstraction layer System Java API
allows developers to quickly build enhanced applications for the web. overview (see page 4253
)
Web Services This integration technology (XML, WSDL, UDDI, and SOAP) allows you to build Publishing the BMC
distributed applications without programming: Remedy AR System
functionality as a web
Use the Set Fields workflow action and a Web Services object to "consume" service (see page 3430)
third-party web services in AR System applications.
Use BMC Remedy AR System to create and "publish" a Web Services
object.
BMC Remedy AR System clients perform data operations on external systems through the AR Enabling plug-ins (see
AR System System server, plug-in service, and plug-in related APIs. The plug-in service page 719)
Plug-Ins 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 The data visualization field provides a framework and services for mid tier-based Data visualization fields
Visualization graphing solutions. It provides an efficient way to add graphical elements (such as (see page 2621)
Field BMC Remedy Flashboards) to AR System forms.
AREA Plug- BMC Remedy provides a special API that allows user logins to be validated from a AREA plug-ins
Ins (BMC data source outside the AR System database. This API is called the AR System introduction (see page
Remedy AR External Authentication (AREA) API. ) and Installing
System sample AREA
External implementations (see
Authentication) page )
Filter API Plug- The filter API enables you to use filters to permit other applications to make calls Integration
Ins back into BMC Remedy AR System. considerations (see
page )

Method Description Section or topic
ARDBC Plug- AR System Database Connectivity enables you to access and manipulate data that AR Filter API plug-ins
Ins (BMC is not stored in BMC Remedy AR System. introduction (see page
Remedy AR Using the ARDBC API, you can create plug-ins used by AR System server to 722)
System manage data. These plug-ins are loaded at run time and implement calls that are
Database analogous to the set, get, create, delete, and get-list API calls for entries in a form.
Connectivity)
Vendor Forms Vendor forms allow BMC Remedy AR System to present data from external Vendor forms
sources as entries in an AR System form. Vendor forms require you to have an introduction (see page
ARDBC plug-in installed and configured. 838)
View Forms View forms allow direct read-and-write access to data in database tables that are View forms introduction
not owned by BMC Remedy AR System. This allows direct access to these tables, (see page 717)
as if they were owned by BMC Remedy AR System, without programming,
database replication, or synchronization.
SQL Database Third-party tools with appropriate permissions can access any information in the AR SQL database access
Access System database. In addition, AR System workflow can query other databases. (see page 848)
ODBC Access ODBC (Open DataBase Connectivity) is a standard database access method ODBC database
developed by Microsoft. Using the ODBC driver, any client capable of accessing access introduction
ODBC can have read-only access to AR System forms. Reporting is a common use (see page 850)
of ODBC.
BMC Atrium The BMC Atrium Integration Engine mediates between the AR System server and Integration
Integration vendor applications such as SAP, Oracle, and other applications and databases for considerations (see
Engine (AIE) which adapters are developed. Adapters can come from BMC Remedy, from page )
partners, or from customers.
Command A Command Line Interface (CLI) is available with most AR System clients. This Integration
Line Interface enables a client to be started and passed a set of parameters so that either it is in a considerations (see
(CLI) specific state and displays information or it completes a process and exits with no page )
user interface displayed.
XML Import BMC Remedy AR System can export and import object definitions in XML. Importing object
and Export AR System clients can convert AR System objects to XML and vice versa without definitions (see page
making calls to the AR System server. 3414) and Exporting
When the server exports the file in XML format, it adds a header required to make it objects and data to
a valid XML document. This same header is required for the server to import an XML format (see page
XML file correctly. Otherwise, the file is assumed to be in the standard AR System 1981)
definition format.
Running One of the actions available in AR System workflow is the Run Process action. Running external
External BMC Remedy AR System can use the command line interfaces of other processes introduction
Applications applications to start those applications and pass them initial data. (see page 876)
(Run Process) 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 BMC Remedy SNMP
management consoles and monitor network devices. Agent configuration
(see page 519)
Licensing Authorized integration system vendors (ISVs) can make their applications Making applications
Applications licensable at the application and user levels. licensable for
integration system
vendors (see page 3424)

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 (see page ), Creating and executing BMC Remedy AR System C API
programs (see page 4087) and BMC Remedy AR System Java API overview (see page
4253).
AR System plug-ins introduction (see page 719)

Plug-in types supported by BMC Remedy AR System (see page 720)
AR Filter API plug-ins introduction (see page 722)
AREA plug-ins introduction (see page 750)
ARDBC plug-ins introduction (see page 753)
Installed plug-in components (see page 770)
Creating C plug-ins (see page 771)
C plug-in naming conventions (see page 772)
Configuring the Java plug-in server (see page 773)
Creating Java plug-ins (see page 779)
Configuring the AR System server to access a plug-in server (see page 782)
Running the plug-in server (see page 784)
Common plug-in C functions and Java methods (see page 786)
Opening Knowledge Management System Configuration form (see page 788)
For information on BMC Remedy ITSM Process Designer , Issues with the ARID plug-in and
BMC Remedy ITSM Social Plug-in refer to the topics in BMC Remedy IT Service Management
Suite documentation.
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.
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 (see page ). 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 (see page 720).
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 (see page ).
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 (see page ).
Note
BMC Remedy AR System also offers two ready-to-use Lightweight Directory

Access Protocol (LDAP) plug-ins. For more information, see LDAP plug-ins in
BMC Remedy AR System (see page 789).
Installed plug-in components (see page 770) 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.
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 (see page 725)

AR Filter API plug-in C function (see page 725)
AR Filter API plug-ins configuration (see page 725)

AR Filter API plug-in Java methods

The methods defined in the ARFilterAPIPluggable interface and the ARFilterAPIPlugin abstract
class are common to all plug-in types. For more information, see the Java plug-in API online
documentation located at ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdoc
VerNum.jar. ( — VerNum represents the release version number.)
AR Filter API plug-in C function

The AR Filter API plug-in API has one function, ARFilterApiCall. For more information, see
ARFilterApiCall (see page 4135).
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 forms:
AR System Administration: Plugin Server Configuration form

AR System Administration: AR System Configuration Generic UI form
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 (see page 262).
Use the configuration files to:
Configure a plug-in server and port

Enable plug-in logging
Troubleshoot plug-in issues
The following topics describe the configuration information of the AR Filter API plug-ins.

AR Registry plug-in configuration (see page 726)

CAI plug-in configuration (see page 727)
CAI RESTful plug-in configuration (see page 729)
Charge-back plug-in configuration (see page 730)
Docs Migration plug-in configuration (see page 731)
File System Sync plug-in configuration (see page 733)
Form Permissions plug-in configuration (see page 734)
FTS plug-in configuration (see page 735)
ITSM Util plug-in configuration (see page 737)
Log Level Change plug-in configuration (see page 738)
NextId plug-in configuration (see page 739)
Registration plug-in configuration (see page 740)
Rule Engine plug-in configuration (see page 742)
SDG plug-in configuration (see page 743)
Twitter Alert Notification plug-in configuration (see page 744)
Twitter User Registration plug-in configuration (see page 746)
Update KAM Mapping plug-in configuration (see page 747)
AR Migrate plug-in configuration (see page 748)
For more information on updating the AR System Administration: AR System Configuration

Generic UI form and AR System Administration: Plugin Server Configuration form, see
Updating configuration settings by using the AR System Configuration Generic UI form (see page
1235), Configuring java plug-in servers (see page 357) and Setting plugin server configuration
options (see page 361).
Related topics
AR Filter API plug-ins introduction (see page 722)
Troubleshooting issues with AR System Filter API plug-ins (see page 4715)
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.
AR System server connectivity

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.

Configuration information
The configuration information of the AR Registry plug-ins is available in the AR System
Administration: Plugin Server Configuration form.
The AR System Administration: AR System Configuration Generic UI form 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
page 1235), Configuring java plug-in servers (see page 357) and Setting plugin server configuration
Related topics
Troubleshooting AR Registry plug-in issues (see page 4716)
Registering, modifying, and de-registering web services (see page 3455)
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 System Administration: AR System Configuration Generic UI form 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 AR System Administration:
Plugin Server Configuration form.


Server-Plugin-Alias: REMEDY.ARF.CAI REMEDY.ARF.CAI myServer:9999
Related topic
Troubleshooting CAI plug-in issues (see page 4717)
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 AR System


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 (see page 4718)
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 AR System

Server-Plugin-Alias: REMEDY.ARF.CBDATA REMEDY.ARF.CBDATA myServer:9999
Related topic
Troubleshooting Charge-back plug-in issues (see page 4719)
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 AR System

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 (see page 4720)
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 AR System

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 (see page 4722)
Form Permissions plug-in configuration

The Form Permissions plug-in is used when you register the BMC Remedy AR System form as a
knowledge base item. This plug-in is called when you open the Accessibility screen of the
Knowledge Registration Wizard. This plug-in also extracts the permissions that are assigned to the
AR System form by using the BMC Remedy AR System API and adds this information to the RKM:
SourceFormPermissions_Temp form.
Plug-in type
Form Permissions is a Java-based Filter API plug-in.

The Form Permissions plug-in connects to the AR System server by using the BMC Remedy AR
System Java API. The Form Permissions plug-in (rkm-form-permissions.jar) is installed in the C:
\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the Form Permissions plug-in is available in the AR System


Server-Plugin-Alias: RMDY.ITSM.RKM.FORMPERMISSIONS RMDY.ITSM.RKM.
FORMPERMISSIONS myServer:9999

</logger>
Related topic
Troubleshooting Form Permissions plug-in issues (see page 4723)
FTS plug-in configuration

The FTS plug-in is used to perform search from a non-indexer server in a server group. 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 configuration information of the FTS plug-in is available in the AR System Administration:

Server-Plugin-Alias: ARSYS.ARF.FTS ARSYS.ARF.FTS myServer:9998
For information about configuring FTS, see the following topics:
Configuring full text search (see page 546)

Related topic
Troubleshooting FTS plug-in issues (see page 4724)
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 AR System

Server-Plugin-Alias: REMEDY.ARF.ITSMUtil REMEDY.ARF.ITSMUtil myServer:
9999

Related topic
Troubleshooting ITSM Util plug-in issues (see page 4726)
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 AR System


Server-Plugin-Alias: RMDY.ITSM.RKM.LOGLEVEL.CHANGE RMDY.ITSM.RKM.
LOGLEVEL.CHANGE myServer:9999
Related topic
Troubleshooting Log Level Change plug-in issues (see page 4727)
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 AR System Administration:


Server-Plugin-Alias: NextId NextId myServer:9999
Related topic
Troubleshooting NextId plug-in issues (see page 4728)
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 AR System

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 (see page 4735)
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 AR System
The AR System Administration: AR System Configuration Generic UI form the Server-Plugin-

Alias setting that points to the correct plug-in server alias. For example:
Server-Plugin-Alias: RMDY.ITSM.RLE RMDY.ITSM.RLE myServer:9999

Related topic
Troubleshooting Rule Engine plug-in issues (see page 4740)
Adding a private queue port number for Software License Management
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 AR System Administration:


Server-Plugin-Alias setting that points to the correct plug-in server alias.
Server-Plugin-Alias: ARSYS.ARF.SDG ARSYS.ARF.SDG myServer:9999
The configuration data of knowledge sources is present in the following forms:
DMT:SpreadsheetColumnSelections
DMT:Spreadsheet
Related topic
Troubleshooting SDG plug-in issues (see page 4742)
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 (see page 746).
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 (aralerttwitter
VerNum.jar — VerNum represents the version number of the release) is installed in the
The configuration information of the Twitter Alert Notification plug-in is available in the AR System
The AR System Administration: AR System Configuration Generic UI form 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 (see page 4743)
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 AR System

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 (see page 4743)
Update KAM Mapping plug-in configuration

The Update KAM Mapping plug-in updates the Knowledge Article Manager (KAM) core fields (
Submit Date and Create Date) by using the Merge Entry call for the Unified Data Management
(UDM) use case, and also updates the KAM Mapping field.
Plug-in type
Update KAM Mapping is a Java-based Filter API plug-in.

The Update KAM Mapping plug-in connects to the AR System server by using the BMC Remedy
AR System Java API. The Update KAM Mapping plug-in (rkm-operations.jar) is installed in the C:
\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.

The configuration information of the Update KAM Mapping plug-in is available in the AR System

Server-Plugin-Alias: RMDY.ITSM.RKM.UPDATEKAMMAPPINGS RMDY.ITSM.RKM.
UPDATEKAMMAPPINGS myServer:9999

</logger>
Related topic
Troubleshooting Update KAM Mapping plug-in issues (see page 4745)
AR Migrate plug-in configuration
Plug-in type (see page 749)

AR System server connectivity (see page 749)

Configuration information (see page 749)
Plug-in type
ARSYS.ARF.ARMIGRATE is a Java-based AR Filter API plug-in.

The DEV to Prod application interacts with the AR Migrate plug-in when a build process, validate
process, deploy process or rollback process is initiated. The AR Migrate plug-in is installed in the
The configuration information of the AR Migrate plug-in is available in the AR System

Server-Plugin-Alias: ARSYS.ARF.ARMIGRATE ARSYS.ARF.ARMIGRATE HOST:9999

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 (see page ) and AREA plug-in C API functions (see page
) 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 (see page 751)

AREA plug-in Java API methods (see page 752)
Installing sample AREA implementations (see page 752)
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 (see page 3665).
AREA plug-in Java API methods

The methods defined in the AREAPluggable interface and the AREAPlugin abstract class are
common to all plug-in types. For more information, see the Java plug-in API online documentation
located at ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
Installing sample AREA implementations

When you install BMC Remedy AR System, you can install a sample Java AREA LDAP
implementation, including an AREA LDAP plug-in. That plug-in provides you with an integration
point between BMC Remedy AR System and LDAP directory services.
You must create a custom plug-in to integrate BMC Remedy AR System with external
authentication services such as Kerberos. See Creating Java plug-ins (see page 779) and AREA
plug-in Java API methods (see page 752) for details.
Example flow of requests and data for an AREA plug-in

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 (see page ).

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 (see page 755)

ARDBC plug-in C API functions (see page 756)
Creating a vendor form for an ARDBC plug-in (see page 757)
ARDBC plug-in Java API methods (see page 758)
ARDBC plug-ins configuration (see page 758)
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 (see page 4106).
A Java ARDBC plug-in can make AR System Java API calls to the AR System server. Use the
ARPluginContext object to create a ARServerUser object. See the Java plug-in server API
online documentation located at
ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
ARDBC plug-in C API functions

An ARDBC plug-in API enables BMC Remedy AR System to:
Implement calls on an external data source that are analogous to set entry, get entry, create
entry, delete entry, and get list C API calls.
Use external data to implement Push Field and Set Field filter, escalation, and active link
actions.
Create, modify, and search for external data through API clients.
Construct query-style character menus.
Present forms, views, and active links on external data in the same manner as internal data.
The data source is transparent to the user.
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 (see page 4117).

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 (see page ).
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 (see page 838).
To create a vendor form for an ARDBC plug-in
1. In Developer Studio, choose File > New > Vendor Form.

2. In the New Vendor Form Wizard, select the server on which you want to create the vendor
form and click Next.
3. Select the ARDBC plug-in to use in the list of Available Vendor Names, and click Next.
4. Choose a table from the list of Available Vendor Tables, and click Next.
Alternatively, type a table name in the Table field, click Validate, then click Next.
5. (optional) On the Field Selection page, choose a key column in the Key Field list box.
6. In the Available Columns list on the Field Selection page, select columns to access in BMC
Remedy AR System. Use the arrow buttons to move them to the Selected Columns list.
New Vendor Form Wizard, Selected Columns


7. Click Finish to create the vendor form.

8. Use Developer Studio to edit the new form, then click File > Save.
ARDBC plug-in Java API methods

The methods defined in the ARDBCPluggable interface and the ARDBCPlugin abstract class are
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
forms:
AR System Administration: Plugin Server Configuration form

AR System Administration: AR System Configuration Generic UI form

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 (see page 262).
Use the configuration files to:
Configure a plug-in server and port

Enable plug-in logging
Troubleshoot plug-in issues
The following topics describe the configuration information of the ARDBC plug-ins.
AppQuery plug-in configuration (see page 759)

Approval Server plug-in configuration (see page 760)
DSO Filter Configuration plug-in configuration (see page 762)
File System plug-in configuration (see page 763)
Pentaho plug-in configuration (see page 765)
RKM Group plug-in configuration (see page 766)
Rule Engine Configuration plug-in configuration (see page 767)
Software Usage plug-in configuration (see page 769)
Related topic
ARDBC plug-ins introduction (see page 753)
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 AR System


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 (see page 4700)
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 System
Administration: AR System Configuration Generic UI form, which contains information about
the log file, related notifications, and their states (active or inactive).
The AR System Administration: AR System Configuration Generic UI form 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, see Updating configuration settings by
using the AR System Configuration Generic UI form (see page 1235).
The configuration information of the Approval Server plug-in is available in the AR System


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 (see page 4702)
Configuring BMC Remedy Approval Server with a separate plug-in server instance (see page 600)
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 AR System

The DSO.FILTERCONFIGURATION.userDefined.filter_configuration_form_name
setting contains the name of the form that has fields for filter name and mapping name.
The DSO.FILTERCONFIGURATION.userDefined.filter_name_field_id and DSO.
FILTERCONFIGURATION.userDefined.mapping_name_field_id settings 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 (see page 4707)
File System plug-in configuration

The File System plug-in provides a file search service in the Microsoft Windows file system and
mapped disks. The File System plug-in enables you to search any type of file in the file system,
based on search criteria. The File System plug-in receives the search parameters from the AR
Vendor form fields and returns the results to the same form.
The plug-in supports different file name qualifications, such as:
Simple qualification, such as the file extension (for example, .doc or .pdf file extensions)

Open qualification for a file name written by using a regular-expression syntax

For more information, see http://docs.oracle.com/javase/tutorial/essential/regex/intro.html.
The File System plug-in returns the file name, file path, the file, and the date of modification as
output. In addition, the plug-in returns document author, title, subject, and keywords as output
values for .doc and .pdf files.
Plug-in type
File System is a Java-based ARDBC plug-in.

The File System plug-in interacts with the AR System server through the AR Vendor form that
contains input fields for search parameters and output fields for viewing search results. The vendor
form that is used is RKM:VF_FileSystem. The File System plug-in (file-system.jar) is installed in
the C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the File System plug-in is available in the AR System

Server-Plugin-Alias: RMDY.ITSM.RKM.FILESYSTEM RMDY.ITSM.RKM.FILESYSTEM
myServer:9999

Related topic
Troubleshooting File System plug-in issues (see page 4701)
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 AR System

Plugin-Alias setting that points to the correct plug-in server alias as follows:
Server-Plugin-Alias: ARSYS.ARDBC.PENTAHO ARSYS.ARDBC.PENTAHO myServer:
9999
Related topic
Troubleshooting Pentaho plug-in issues (see page 4714)
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
The configuration information of the RKM Group plug-in is available in the AR System


Server-Plugin-Alias: RMDY.ITSM.RKM.GROUP RMDY.ITSM.RKM.GROUP myServer:
9999
Related topic
Troubleshooting RKM Group plug-in issues (see page 4704)
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 AR
System Administration: Plugin Server Configuration form.

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 (see page 4705)
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 AR System

Plugin-Alias setting that points to the correct plug-in server alias.
Server-Plugin-Alias: RMDY.ITSM.ASSET.SOFTWAREUSAGE RMDY.ITSM.ASSET.
SOFTWAREUSAGE myServer:9999
Related topic
Troubleshooting Software Usage plug-in issues (see page 4699)
Installed plug-in components

Before you can create AR System plug-ins, you must install this component:
AR System plug-in servers — Automatically installed with BMC Remedy AR System.
Note
In addition to the BMC Remedy AR System 8.1 Java plug-in server and its API, the C
plug-in server, arplugin, and its API are installed.
Installed plug-in files

The plug-in server and Java plug-in API files are typically installed in the following directories:
UNIX — /usr/ar/<serverName>/pluginsvr
Windows — C:\Program Files\AR System\<serverName>\pluginsvr
Component Description
arapiVerNum.jar* Includes the AR System Java API, Java utilities, and AR System server communications
This file is called by Java plug-ins.
arjavaplugin.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.
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 (see page )).
One of these type-specific API calls:
AREA (see AREA plug-in C API functions (see page ))
ARDBC (see ARDBC plug-in C API functions (see page ))
AR Filter (see AR filter API plug-ins introduction (see page ))
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 (see page 787) 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. Add an entry for the plug-in to the plug-in server configuration file. See Configuring the Java
plug-in server (see page ).
At run time, the plug-in server reads the configuration file and loads the specified plug-ins.
C plug-in naming conventions

When you create a C plug-in, use the following naming conventions and memory management
recommendations.
Managing memory
Do not free memory that the plug-in passes to your functions as arguments or that you return to the
plug-in. Plug-ins can allocate and deallocate memory associated with the object argument for
each call. The plug-in does not deallocate this memory.
Specifying input and return values

In a C API program, developers specify input values for the functions and receive return values. In
a plug-in program, the plug-in provides the input values to the plug-ins, and the plug-ins provide
return values.
If the AR System server returns AR_RETURN_WARN or AR_RETURN_OK to the arplugin log

file after a call is issued, the plug-in considers that call successful. The plug-in considers the call
unsuccessful if the server returns AR_RETURN_ERROR or AR_RETURN_FATAL.
If you do not implement a call, the plug-in performs a default action. The default action might be to
proceed or to return an error message.
Protecting global information

To ensure thread safety, you must protect any global information or resources that you access
through plug-in API calls with appropriate mutual exclusion locks. Global information and resource
protection applies to all plug-in calls except ARPluginIdentify, ARPluginInitialization,
ARPluginSetProperties, and ARPluginTermination, which are always called by one thread at a
time.
At run time, the plug-in server reads the configuration file and creates the plug-ins that the file
specifies. After the plug-in server creates the plug-ins, they remain active until a system failure or

until you modify the plug-in configuration information and restart the plug-in server. For information
about restarting the plug-in server, see Restarting the plug-in server using the Set Server Info
command (see page ).
Configuring the Java plug-in server

Configure the Java plug-in server in the AR System Administration: Plugin Server
Configuration form. The configuration is stored 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 AR System
Administration: Plugin Server Configuration form and save the form, 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 Configuring java plug-in servers (see page 357), for descriptions, valid values, and default
values for the Java plug-in server configuration options.
Note
See the Configuring after installation (see page 241) section for configuration of the C-
based plug-in server, arplugin.
Using multithreading in the Java plug-in server (see page 774)

Using the Java plug-in server for dynamic plug-in loading (see page 775)
Using the C plug-in server for dynamic plug-in loading (see page 776)
Using plug-in naming conventions (see page 777)
Restarting the plug-in server using the Set Server Info command (see page 778)

Overriding values from ar.cfg or ar.conf (see page 779)
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 Number Of Selector Threads field on
the AR System Administration:Plugin Server Configuration form.
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 Number Of Core Threads field on the AR System
Administration:Plugin Server Configuration form.
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 Work Queue Task Threshold field on the AR System
Administration:Plugin Server Configuration form.
To specify how frequently the system checks to see whether the task threshold has been
exceeded, use the Work Queue Monitor Log Interval field on the AR System Administration:
See Setting global plug-in server options (see page 359) and Setting plugin server configuration

Using the Java plug-in server for 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.
To enable dynamic plug-in loading, you must specify a reload delay before starting the plug-in
server (use the Reload Delay configuration option in the AR System Administration: Plugin
Server Configuration form). For more information on AR System Administration: Plugin Server
Configuration form, see Setting plugin server configuration options (see page 361).
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 page
).
The following example provides the steps to configure the Atrium SSO plug-in using only the Java
plug-in server.
To configure the Atrium SSO plug-in using only the Java plug-in server
1. Make the following changes in the AR System Administration: AR System Configuration

Generic UI form:
Comment out the Plugin: areaatriumsso.dll entry (if it exists) and also comment out all the
native area plug-in related entries.
2. Make the following changes in the AR System Administration: Plugin Server
Configuration form:
a. Delete the ARSYS.AREA.ATRIUMSSO plug-in.
b. Create a new plug-in with the following details:

Field Field value

name
Plugin
AREA
Name
Plugin
com.bmc.arsys.plugins.sso.AtriumSSOPlugin
Class
name
Path
C:/Program Files/BMC Software/ARSystem/pluginsvr/arssoplugin91_build001.jar
Elements
C:/Program Files/BMC Software/ARSystem/pluginsvr/atsso-sdk.jar
C:/Program Files/BMC Software/ARSystem/pluginsvr/atsso-common.jar
C:/Program Files/BMC Software/ARSystem/pluginsvr/bcprov-jdk15-145.jar
C:/Program Files/BMC Software/ARSystem/pluginsvr/stax-1.2.0.jar
C:/Program Files/BMC Software/ARSystem/pluginsvr/stax-api-1.0.1.jar
C:/Program Files/BMC Software/ARSystem/pluginsvr/json.jar
For more information on creating, modifying, and deleting plug-ins and their configurations, see
Working with Java plug-ins (see page 365) and Configuring java plug-in servers (see page 357).
For more information on updating the AR System Administration: AR System Configuration

Generic UI form, see Updating configuration settings by using the AR System Configuration
Generic UI form (see page 1235).
Note
For more information about Atrium SSO integration, see Configuring BMC Atrium SSO
integration in BMC Atrium Single Sign-On 9.0 documentation.
Using the C plug-in server for dynamic plug-in loading

Plug-ins are configured in the ar.cfg file. A new plug-in is added to the plug-in server through the
AR System server. Previously, adding a new plug-in definition required that you stop and restart
the AR System server. An API interface in the plug-in server can add the new plug-in definitions
dynamically, without stopping and restarting the AR System server.
See the plug-in server configuration file (ar.cfg or ar.conf (see page 1065)).

To add the plug-in information to the C plug-in server configuration file
1. Double-click the driver.exe file.

The default location of this file is C:\Program Files\BMC
Software\ARSystem\Arserver\api\driver.
2. Enter the required login and server information.
3. Enter the gsi (Get Server Info) command to get the current plug-in information.
4. Enter the following details:
Number of server info operations--The number of servers for which you want the
current plug-in information.
Operation--The operation number for getting the current plug-in information that is
present in the ar.cfg file.
A list of current plug-ins is displayed.
5. Enter the ssi(Set Server Info) command to add the new plug-ins.
Note
If you enter the ssi command without entering the gsi command first, the old
plug-in entries are overwritten and only the new entries are recorded.

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 AR System
Administration:Plugin Server Configuration form are done to the C plug-in file or Java plug-in
form, you are able to restart only the plug-in server instead of restarting the AR System server.
To restart the plug-in server using the Set Server Info command
1. Double-click the driver.exe file. The file is located in the following path:
(Windows) <ARInstallationFolder>\Arserver\api\driver
(UNIX) <ARInstallationFolder>/bin
Note
On UNIX, set the LD_LIBRARY_PATH environment variable to the directory

where the arserver.exe is located. For example, export
LD_LIBRARY_PATH= opt/bmc/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 (see page 4103).
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.)
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 (see page 780)

Writing a Java plug-in (see page 780)
About classes, instances, and shared data

Two or more Java plug-in classes can be configured in a plug-in set or group in the AR System
Administration: Plugin Server Configuration form. 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 AR System
Administration: Plugin Server Configuration form 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 (see page 770)
for installation and verification.)
AR System Java API files. (See Installed plug-in components (see page 770) 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 (see page 770).)
4. Create a new class that will implement one of the interfaces listed in Creating Java plug-ins
(see page ), 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 (see page ).
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.
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 System
Administration: AR System Configuration Generic UI form. (See Setting server passwords,
RPC options, and plug-in timeouts (see page 288).)
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 System Administration: AR System
Configuration Generic UI form 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.
For more information on using AR System Administration: Server Information form, see Updating
configuration settings by using the AR System Configuration Generic UI form (see page 1235).
Defining plug-in aliases (see page 782)

Plug-in aliases scenarios (see page 783)
Defining plug-in aliases

You define plug-in aliases in the AR System Administration: AR System Configuration Generic
UI form. 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.
See Server-Plugin-Alias option in Configuration settings S-Z (see page 1226).
For more information on using AR System Administration: Server Information form, see Updating
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 (see page 783)
Workflow accessing the ARF plug-in scenario (see page 783)
Vendor form accessing the ARDBC plug-in scenario (see page 783)
AR System server accessing the AREA plug-in scenario (see page 784)
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.
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 (see page 773).
In this topic:
Logging plug-in information (see page 784)

Logging exceptions for calls to Java plug-ins (see page 785)
About C plug-in exception handling (see page 786)
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 on the Log
Files tab of the AR System Administration: Server Information form. For more information, see
Setting log files options (see page 268).
Java plug-ins can log messages using the logMessage method of their ARPluginContext object.
See the Java plug-in API online documentation located at
ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar for details.
The Java plug-in server uses the log4j utility. Set the log level and other logging configuration in
the log4j_pluginsvr.xml file. Comments in the sample file describe the log configuration options.
Logging exceptions for calls to Java plug-ins

When a run-time exception or an ARException class error occurs during a Java plug-in server call
to a Java plug-in, the following information is now recorded in the ARServerInstallDir
\Arserver\Db\arjavaplugin.log file:
The name of the plug-in

This name matches the name of the corresponding plug-in library registered in the Java
plug-in configuration file, pluginsvr_config.xml. For example, if the library is registered as
<name>DSO.FILTERCONFIGURATION</name>, the plug-in name in the log file is DSO.
FILTERCONFIGURATION.

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 (see page 3451).
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.
Common plug-in C functions and Java methods

This section describes the calls or methods common to all plug-in types including:
Common C plug-in functions (see page 787)

Common Java plug-in methods (see page 788)
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 (see page 4106).
Common Java plug-in methods

The methods defined in the ARPluggable interface and the ARPlugin abstract class are
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.
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.
Integrating with a directory service

This section describes how to configure and use the ARDBC and AREA LDAP plug-ins to integrate
BMC Remedy AR System with a directory service.
LDAP plug-ins in BMC Remedy AR System (see page 789)

Using the ARDBC LDAP plug-in (see page 790)
Configuring the ARDBC LDAP plug-in (see page 790)
Building BMC Remedy AR System forms for directory services (see page 793)
Using the AREA LDAP plug-in (see page 799)
ARDBC LDAP example - Accessing inetorgperson data (see page 806)
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 (see page ).

AR External Authentication (AREA) LDAP — Authenticates AR System users against

external LDAP directory services. See Using the AREA LDAP plug-in (see page ).
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
(see page ).
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 (see page 797).
LDAP does not support transactions. Consequently, when an object is created, modified, or
deleted, the change does not roll back if subsequent workflow in the AR System server
detects an error condition.
The distinguished name and password specified in the ARDBC LDAP configuration are
used to connect to any directory service referenced in LDAP search URLs.
Only server-based certificates are supported.
Configuring the ARDBC LDAP plug-in

You must configure the ARDBC LDAP plug-in before you create the vendor form used to access
user information in your particular LDAP server.
To configure the ARDBC LDAP plug-in
1. In the AR System Administration Console, click System > LDAP > ARDBC Configuration.
The ARDBC LDAP Configuration form opens in New mode.
ARDBC LDAP configuration form


2. In the Host Name field, enter one or more host names of the directory service from which
you want information for the vendor form. You can specify a space-separated list of host
names up to 255 characters long. Starting with the first host name in the list, BMC Remedy
AR System tries to connect to each server until it is successful.
If you use Secure Socket Layer (SSL), this host name should match the name for which the
server's certificate was issued.
3. In the Port Number field, enter a port number for this directory service. The default port
number is 389. (For an SSL connection, the default is 636.)
4. In the Bind User field, enter the distinguished name of the user account that the ARDBC
LDAP plug-in uses to log in to the directory service. The administrator who set up the LDAP
service designated this name. With the vendor form, some LDAP servers allow you to make
an anonymous connection. If you plan to use an anonymous connection, leave the Bind
User and Bind Password fields blank.
Otherwise, use a standard distinguished name such as cn=manager, dc=remedy, dc=com
.
5. In the Bind Password field, enter the password for the user account. (For security,
asterisks replace the characters you enter for the password.)
If you leave the Bind Name and Password fields blank, you are connected anonymously.
6. To use a Secure Socket Layer (SSL) connection, select Yes in the Using Secure Socket
Layer field; otherwise, accept the default value No. If you select Yes, the Certificate
Database field becomes active, and you can enter a certificate database as described in
step 7 (see page 791). 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.
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 20010928060000Z

Time servers, and it is recommended.
AD 1 YYYYMMDDHHMMSS.0Z This format is recognized only by Microsoft 20010928060000.0Z

Generalized Active Directory servers.
Time
UTC Time 2 YYMMDDHHMMSSZ This is a historical format and does not indicate 010928060000Z
the century. It is not recommended.
For more information, see Configuring after installation (see page 241).
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.
Tip
The default Directory Page Size is 10000. However setting Directory Page Size to
a lower value, such as 1000, might help to improve your system's performance
while you design and create vendor forms.
Note
Directory Page Size value should be less than or equal to the maximum page
size setting on the LDAP server. For more information on ARDBC-LDAP-Page-
Size, see Configuration settings A-B (see page 1148).
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.
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 System configuration settings with the parameters you
specified in this form.
For more information, see Configuring after installation (see page 241).
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 (see page 793)

Creating a vendor form to represent a collection of LDAP objects (see page 794)
Identifying objects uniquely (see page 795)
Supporting object creation (see page 796)
Improving ARDBC LDAP runtime performance (see page 798)
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 AR Database
service System
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 (see page 809).

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 (see page 2400).
For general information about creating vendor forms, see Creating vendor forms (see page 838).
For an example of how to create a vendor form for LDAP data, see ARDBC LDAP example -
Accessing inetorgperson data (see page 806).
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:
Creating an objectclass field (see page 796)

Specifying multivalued attributes (see page 797)
Generating and assigning a distinguished name (see page 797)
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 (see page 797)).
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.
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 (see page ).
Configuring the AREA LDAP plug-in (see page 799)

Configuring AREA LDAP group search (see page 804)
Configuring AR System servers to use the AREA LDAP plug-in (see page 806)
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. BMC Remedy AR System supports multiple AREA LDAP configurations.
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 (Click the image to expand it.)

If any AREA LDAP server configurations 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 server 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:

3.
Host Name — Name of one or more servers on which the directory service is hosted.
You can specify a space-separated list of host names up to 255 characters long.
Starting with the first host name in the list, BMC Remedy AR System tries to connect
to each server until it is successful.
Port Number — Number of the port on which the directory service is listening.
Bind User
— Distinguished name for this configuration. The distinguished name is the name for
a user account that has read permissions and can search the directory service for
user objects.
Bind Password — Password for the distinguished name specified for the Bind user.
Use Secure Socket Layer? — Yes/No toggle field. To specify an SSL connection to
the directory service, select Yes to enable the Certificate Database field.
Certificate Database — Name of the directory containing the certificate database
file.
Failover Timeout — Number of seconds in which the directory service must respond
to the plug-in server before an error is returned. Minimum value is 0 (connection must
be made immediately). This value cannot be higher than the value of the External-
Authenticaion-RPC-Timeout parameter.
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:

4.
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. 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 mark Overridden license types
number
Application FTS Reserved Write
0 - - - -
1 - - - X
2 - X - -
3 - X - X
4 - - X -
5 - - X X

License mark Overridden license types

number
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. Click Save Current Configuration. The system updates the AR System configuration
settings 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 System configuration settings.
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 (see page 805)).
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

3. Click Apply and OK.
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 (see page 804)).
To ignore excess groups
2. In the Group Mapping box, select the Ignore Excess Groups check box.
3.
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 (see page 829).
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 (see
page ).
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 (see page ) and Configuring the ARDBC
LDAP plug-in (see page ).
Creating the inetorgperson vendor form (see page 806)

Attaching fields to represent inetorgperson data (see page 808)
Defining a filter to generate a DN (see page 809)
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. 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 (see page ).

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. 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 Entry Mode: Required Read/Write Default Value: none Vendor Information Column: cn
Name
Organization Entry Mode: Required Read/Write Default Value: People Vendor Information Column: ou[,]*
Unit
In this scenario, the form looks like the form in the following figure.
The inetorgperson form

Integrating BMC Remedy Single Sign-On with

other BMC products
Important
The BMC Remedy Single Sign-On installer does not perform unintegration. If the user
wants to integrate BMC Remedy Single Sign-On with a supported BMC application which
is already integrated with BMC Atrium Single Sign-On, the previous integration has to be
removed manually.
The following topics provide information and instructions for integrating BMC products with BMC
Atrium Single Sign-On:
Integrating BMC Remedy Single Sign-On with BMC Remedy AR System (see page 812)
Integrating BMC Remedy Single Sign-On with BMC Remedy Mid Tier (see page 815)
Integrating BMC Remedy Single Sign-On with BMC Remedy with Smart IT or BMC MyIT
(see page 818)
Integrating BMC Remedy Single Sign-On integration with BMC Analytics for BSM (see page
821)
Migrating from BMC Atrium Single Sign-On to BMC Remedy Single Sign-On (see page 826)
Watch a video on integration at https://www.youtube.com/watch?v=Ze9TvBA51sw&feature=youtu.

be.
Related topics

Troubleshooting BMC Remedy Single Sign-On integration issues
Integrating BMC Remedy Single Sign-On with BMC Remedy

AR System
Important

removed manually.
To integrate BMC Remedy Action Request System (BMC Remedy AR System) with the BMC
Remedy Single Sign-On, you must run the BMC Remedy Single Sign-On installer on the computer
on which the BMC Remedy AR System server is installed. You must have the BMC Remedy
Single Sign-On server and the BMC Remedy AR System server running before performing the
integration.
Before you begin

Ensure that you have installed the following applications:
BMC Remedy Single Sign-On

BMC Remedy Mid Tier
For more information, see Installing BMC Remedy AR System and Installing BMC Remedy
Single Sign-On .
To run BMC Remedy Single Sign-On on the BMC Remedy AR System server
1. Unzip the BMC Remedy Single Sign-On files.

2. Run the installation program (setup.exe).
The setup executable is located in the Disk1 directory of the extracted files.
3. In the lower-right corner of the Welcome panel, click Next.
4. Review the license agreement, click I agree to the terms of license agreement, and then
click Next.
5. Accept the default destination directory or browse to select a different directory, and then
click Next.
6. Select the Integrate with BMC Remedy AR System option, and then click Next.
Important
After successful integration, the server hosting BMC Remedy AR System will be
restarted.
7. Enter the directory path where BMC Remedy AR System application is installed.
8. Enter the URL for communication between BMC Remedy Single Sign-On and agent.

8.
9. Check the installation preview and then click Install to complete the integration.
(optional) Silent integration of BMC Remedy Single Sign-On with BMC Remedy
AR System
You may integrate BMC Remedy Single Sign-On with BMC Remedy AR System using the silent
mode.
To integrate BMC Remedy Single Sign-On with BMC Remedy AR System using the silent
mode
Run the installer with the -i silent option:
(Windows) setup.exe -i silent -

DOPTIONS_FILE=<path_to_txt_file_with_installation_options>
(UNIX) sh setup.bin -i silent -
The options file is as follows:
-P installLocation=<path where product info will be located>
-A productRemedySSO
-J AR_TYPE=true

-J AR_HOME=<path_to_AR_server_home>
-J INT_URL=<internal_RSSO_url>
Related topics

Troubleshooting BMC Remedy Single Sign-On integration issues (see page 4768)

Mid Tier
Important
removed manually.
To integrate BMC Remedy Mid Tier with BMC Remedy Single Sign-On, you must run the BMC
Remedy Single Sign-On installer on the computer on which BMC Remedy Mid Tier is installed.
Before you begin

Ensure that you have installed the following applications:
BMC Remedy Single Sign-On

BMC Remedy Action Request System (BMC Remedy AR System)
BMC Remedy Mid Tier
For more information, see Installing BMC Remedy AR System and Installing BMC Remedy
Single Sign-On .
To run BMC Remedy Single Sign-On on BMC Remedy Mid Tier


Home
2. BMC Software Confidential. BladeLogic Confidential.
click Next.
click Next.
6. Select the Integrate with BMC Mid Tier option, and then click Next.
Important
After successful integration, the server hosting BMC Remedy Mid Tier will be
restarted.
7. Enter the directory path where BMC Remedy Mid Tier is installed.
8. Enter the URL to redirect unauthenticated user requests to BMC Remedy Single Sign-On
for authentication.

(optional) Silent integration of BMC Remedy Single Sign-On with BMC Remedy
Mid Tier
You may integrate BMC Remedy Single Sign-On with BMC Remedy Mid Tier using the silent
mode.
To integrate BMC Remedy Single Sign-On with BMC Remedy Mid Tier using the silent mode

-A productRemedySSO
-J MT_TYPE=true
-J MT_HOME=<path_to_Midtier_home>
-J MT_PATH=<path_to_Midtier_server_home>
-J EXT_URL=<external_RSSO_url>
Related topics



with Smart IT or BMC MyIT
Important
removed manually.
This topic describes how to integrate BMC Remedy Single Sign-On with Smart IT (Smart IT) or
BMC MyIT.
Before you begin
Install BMC Remedy Single Sign-On and configure realms to support the needed
authentication methods.
Install BMC MyIT 2.1 or later.
Verify that access to the BMC MyIT and BMC Remedy Single Sign-On servers occurs
through the same domain. Otherwise, deploying the BMC Remedy Single Sign-On agent
will not work.
To integrate BMC Remedy Single Sign-On with BMC MyIT

click Next.
click Next.
6. Select the Integrate with BMC MyIT / BMC SmartIT option, and then click Next.
Important
After successful integration, the server hosting BMC Remedy with Smart IT or
BMC MyIT will be restarted.

7. Enter the directory path where BMC MyIT is installed.

8. Enter the directory path to the BMC MyIT web server.
9. Enter MyIT user credentials.
for authentication.

(optional) Silent integration of BMC Remedy Single Sign-On with BMC MyIT
You may integrate BMC Remedy Single Sign-On with BMC MyIT using the silent mode.
To integrate BMC Remedy Single Sign-On with BMC MyIT using the silent mode

-A productRemedySSO
-J MI_TYPE=true
-J MI_HOME=<path_to_Midtier_home>
-J MI_WEBSERVER_PATH=<path_to_Midtier_server_home>

-J MI_USER=<MyIT_user_name>
-J MI_USER_PASSWD=password
-J MI_USER_PASSWD_CNFRM=password
Related topics

Integrating BMC Remedy Single Sign-On integration with BMC

Analytics for BSM
The following topics provide information related to integrating BMC Remedy Single Sign-On with
BMC Analytics for BSM.
Prerequisites for Integrating BMC Remedy Single Sign-On with BMC Analytics for BSM (see
page 821)
Perform BMC Remedy Single Sign-On integration with BMC Analytics for BSM (see page
823)
Prerequisites for Integrating BMC Remedy Single Sign-On with BMC Analytics for
BSM
This topics provides prerequisites for integrating BMC Remedy Single Sign-On with BMC Analytics
for BSM.
Software Requirement (see page 821)

Pre-integration procedures (see page 822)
Software requirement
The Tomcat for SAP BI (Business Intelligence) must use Java 1.7 or a higher version.
To enable Java 1.7 or higher for SAP B1 4 bundled Tomcat service
1. Rename tomcat7w.exe to BOEXI40Tomcatw.exe in the <tomcat>/bin folder.

2. Double click BOEXI40Tomcatw.exe.
3.
3. Click the 'Java' tab in Apache Tomcat for BI 4 Properties and change following
configurations.
Configuration Before Change After Change
Java Virtual C:\Program Files (x86)\SAP BusinessObjects\SAP <JAVA_HOME>\jre\bin\server\jvm.dll

Machine BusinessObjects Enterprise XI 4.0
\win64_x64\sapjvm\\jre\bin\server\jvm.dll
Java C:\Program Files (x86)\SAP C:\Program Files (x86)\SAP

Classpath BusinessObjects\tomcat\bin\bootstrap.jar;C:\Program Files BusinessObjects\tomcat\bin\bootstrap.
(x86)\SAP BusinessObjects\tomcat\bin\tomcat-juli.jar;C: jar;C:\Program Files (x86)\SAP
\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects\tomcat\bin\tomcat-
BusinessObjects Enterprise XI 4.0 juli.jar;<JAVA_HOME>\tools.jar
\win64_x64\sapjvm\lib\tools.jar
Note
<JAVA_HOME> is the home directory of Java 1.7 or higher version.
4. Rename BOEXI40Tomcatw.exe back to tomcat7w.exe.

5. Restart 'Apache Tomcat for BI 4' service.
Pre-integration procedures
Take a backup of the following file and then delete it:
<tomcat>/webapps/BI/WEB-INF/webagent.jar
If BMC Analytics for BSM does not use BMC Atrium Single Sign-On for authentication, perform the
following steps:
1. Enable Trusted Authentication in SAP BI.

a. Log on to the SAP BusinessObjects Central Management Console (http://<server>:
<port>/BOE/CMC) with administrative rights.
b. Click the Authentication link in the Manage area.
c. Double click the Enterprise option. The "Enterprise" dialog box opens.
d. Scroll down until you see "Trusted Authentication".
i. Ensure that the Trusted Authentication is enabled checkbox is selected
ii. Set the following configuration values:
Shared Secret Validity Period (days): 1000
Trusted logon request is timeout after N millisecond(s) (0 means no
limit): 10000
iii. Click New Shared Secret.
e. Click Download Shared Secret. Remember the location of downloaded file (
TrustedPrinciple.conf) which will be used later.
f. Click Update.
2. Edit <tomcat>/webapps/BI/index.jsp.
a.
2.
a. Enable SSO.
i. Search this string: String SSOEnabled = "0".
ii. Replace string 0 above with 1.
b. Change SharedSecret value.
i. Open the downloaded file 'TrustedPrinciple.conf' in step 1.5 and copy the
value of 'SharedSecret'.
ii. Search this string: String sharedSecret = "BSMAnalyticsSecret".
iii. Replace the string BSMAnalyticsSecret above with the value copied from
'TrustedPrinciple.conf'.
3. Edit <tomcat>/webapps/BI/WEB-INF/web.xml, and replace its content with the content of
<tomcat>/webapps/BI/WEB-INF/web.xml.sso.
4. Edit <tomcat>/webapps/BOE/WEB-INF/config/default/BIlaunchpad.properties, and change
the url.exit property value to /BI/atssologout.html, i.e. url.exit=/BI/atssologout.html.
Perform BMC Remedy Single Sign-On integration with BMC Analytics for BSM (see page
823)
Perform BMC Remedy Single Sign-On integration with BMC Analytics for BSM
Important
removed manually.
If you plan to use BMC Remedy Single Sign-On as your method of authentication, you must install
and configure the BMC Remedy Sign-On server before installing BMC Analytics for Business
Service Management (BMC Analytics for BSM). Also, ensure that any users that you want to use in
BMC Analytics for BSM exist in the BMC Remedy Single Sign-On server.
Before you begin
Install and configure the BMC Remedy Sign-On server first and then install BMC Analytics
for BSM.
BMC Analytics for BSM is compatible with Apache Tomcat or Microsoft IIS. If you are using
BMC Single Sign-On with BMC Analytics for BSM, only Apache Tomcat is supported.
Ensure that all the prerequisites mentioned in Prerequisites for Integrating BMC Remedy
Single Sign-On with BMC Analytics for BSM (see page 821) are met.

Ensure that any users that you want to use in BMC Analytics for BSM exist in the BMC
Remedy Sign-On server. See Managing users and Managing user groups.
Ensure that the DNS domain or subdomain of your SAP BusinessObjects BI Platform host is
consistent with the 'Cookie Domain' configuration of the BMC Remedy Single Sign-On
server.
To integrate BMC Remedy Single Sign-On with BMC Analytics for BSM

click Next.
click Next.
6. Select the Integrate with BMC Analytics option, and then click Next.
Important
After successful integration, the server hosting BMC Analytics for BSM will be
restarted.
7. Enter the directory path where BMC Analytics for BSM is installed.
for authentication.

(optional) Silent integration of BMC Remedy Single Sign-On with BMC Analytics for BSM
You may integrate BMC Remedy Single Sign-On with BMC Analytics for BSM using the silent
mode.
To integrate BMC Remedy Single Sign-On with BMC Analytics for BSM using the silent mode

-A productRemedySSO
-J AL_TYPE=true
-J ANALYTICS_HOME=<path_to_Midtier_home>

-J ANALYTICS_WEBSERVER_PATH=<path_to_Midtier_server_home>
Related topics

Migrating from BMC Atrium Single Sign-On to BMC Remedy

Single Sign-On
The following table provides the steps for migrating from BMC Atrium Single Sign-On to BMC
Remedy Single Sign-On.
1. Install BMC Remedy Single Sign-On BMC Remedy Single Sign-On installer does the following:
1. Deploys the 'rsso' web application on the existing Apache Tomcat web
server.
2. Creates the 'rsso' database on the specified RDBMS and provisions
this database with the essential data.
2. Configuring BMC Remedy Single Sign- BMC Remedy Single Sign-On can be configured to process end user's
On (see page 654) authentication against AR, SAML v2, and LDAP user stores,
3. Integrate BMC Remedy AR System with Perform the following steps to integrate BMC Remedy AR System with BMC
BMC Remedy Single Sign-On Remedy Single Sign-On
1. Unintegrate BMC Remedy AR System from BMC Atrium Single Sign-

On.
2. a. Stop BMC Remedy AR System.
b. Modify and save the following files.
Note: Take a backup prior to modifying the files.
File Modifications
ar.cfg (arsystem/conf folder) Remove the following

entries:
Atrium-SSO-Location
Atrium-SSO-Admin-
User
Atrium-SSO-Admin-
Password

File Modifications
pluginsvr_config.xml Remove the plugin entries.

(arsystem/pluginsvr) For example,
!-- Atrium SSO AREA
Plug-in -->
<plugin>
…
</plugin>
c. In the pluginsvr folder take the backup of following files and

then delete them.
atsso-sdk.jar
atsso-common.jar
json.jar
simple-xml-2.5.3.jar
stax-1.2.0.jar
stax-api-1.0.1.jar
d.Restart the BMC Remedy AR System.
2. Integrate BMC Remedy Single Sign-On with BMC Remedy AR System

(see page 812).
4. Integrate BMC Remedy AR System with Perform the following steps to integrate BMC Remedy Mid Tier with BMC
BMC Remedy Mid Tier Remedy Single Sign-On
1. Unintegrate BMC Remedy Mid Tier from BMC Atrium Single Sign-On.
a. Stop BMC Remedy Mid Tier.
b. Take a backup of the “atssoAgents” folder under apache
/tomcat.. and then delete it.
c. Modify and save the following files.
Note: Take a backup prior to modifying the files.
File Modifications
config.properties Comment the line that starts with:
(Midtier/WEB-INF arsystem.authenticator
/classes/)
web.xml Remove the following filter definition and filter

mapping definitions
(Midtier/WEB-INF
/) 



Note: Make sure that there are no references to ASSO

in this file.
d. In the Midtier/WEB-INF/lib folder, take a backup of following files and then

delete them.
atsso-common.jar
atsso-sdk.jar
json.jar
simple-xml-*.jar
stax-1.2.0.jar
stax-api-1.0.1.jar
webagent.jar
2. Integrate BMC Remedy Mid Tier with BMC Remedy Single Sign-On (see
page 815).
Related topics
Orientation
AR System external authentication

You can use plug-ins and the AR System External Authentication (AREA) API to integrate BMC
Remedy AR System with external user authentication services. In addition, you can configure BMC
Remedy AR System to use a combination of internal and external authentication, including OS-
based authentication.
Enabling AREA authentication (see page 829)

Configuring authentication processing (see page 829)
Setting up the AREA hub (see page 836)

Enabling FIPS support for BMC Atrium SSO (see page 837)
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 (see page )
Common plug-in C functions and Java methods (see page )
AREA plug-in C API functions (see page )
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 (see page ).
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 (see page
).
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 (see page ).
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 (see page 830)

Authenticating unregistered users (see page 830)
Cross-referencing blank passwords (see page 831)
Specifying authentication chaining mode (see page 831)
Determining AREA behavior (see page 832)

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 (see page ).
Note
If the user group information is returned through external authentication, you

cannot be a part of any administrator group. You can be a part of the administrator
group only from the User form.
Cross Reference Blank Password — If a user does not provide a password, BMC
Remedy AR System tries to cross-reference the user with an external source. See Cross-
referencing blank passwords (see page ).
Important
To use external authentication, you must set the External Authentication Server RPC
Program Number field to 390695.
Authenticating unregistered users

When the Authenticate Unregistered Users option is selected, BMC Remedy AR System first
attempts to find the user in the User form. If the user exists in the User form, BMC Remedy AR
System attempts authentication through that form. If the user does not exist in the User form, BMC
Remedy AR System attempts authentication through the AREA plug-in.
Note
You cannot get admin group information from the user's group list if the user is returned
through external authentication. You can get admin group information only from the User
form.

To authenticate unregistered users
2. In the External Authentication Server RPC Program Number field, enter 390695.
3. Select the Authenticate Unregistered Users check box.
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 (see page 833).
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 - BMC Remedy AR System attempts to authenticate the user by using the User form and then the AREA
AREA plug-in.
AREA - BMC Remedy AR System attempts to authenticate the user by using the AREA plug-in and then the User
ARS form.

Mode Description
ARS - OS - BMC Remedy AR System attempts to authenticate the user by using the User form, then Windows or
AREA UNIX authentication, and then the AREA plug-in.
ARS - BMC Remedy AR System attempts to authenticate the user by using the User form, then the AREA plug-
AREA - OS in, and then Windows or UNIX authentication.
Note
Ensure that you configure the Pluggable Authentication Module (PAM)

configuration file on the UNIX system for OS authentication to work. Create a file
auth in the /etc/pam.d folder. The file contains the authentication parameters and
security settings specific for UNIX system, for example:
#%PAM-1.0
auth required pam_unix.so
Note
BMC Remedy AR System behaves differently depending on the authentication

chaining mode you choose and other external authentication parameters you
specify. See Determining AREA behavior (see page ).
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 (see page ).
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 (see page 833)
AREA behavior when the RPC program number is 0 (see page 835)
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.
the User form.
ARS - OS - AREA
the User form.
Authentication is performed using OS authentication. If successful, user information is retrieved from
the OS.
If OS authentication fails, user authentication is performed using AREA LDAP. If AREA LDAP
authentication is successful, user information is retrieved from AREA LDAP.
ARS - AREA - OS
the User form.
Authentication is performed using AREA LDAP. If successful, user information is retrieved from
AREA LDAP.
If AREA LDAP authentication fails, the user is authenticated using OS authentication. If OS
authentication is successful, user information is retrieved from the OS.
User exists with no password in User form

chaining mode
Off
Authentication is performed using AREA LDAP password. User information is retrieved from the User
form.


chaining mode
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.
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.
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
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
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
Authentication is performed using AREA LDAP. If successful, user information is retrieved from AREA
LDAP.
If AREA LDAP authentication fails, authentication is attempted using User form. If User form
authentication is successful, user information is retrieved from the User form.
ARS - OS -
AREA Authentication is performed using the AR System User form. If successful, user information is


chaining mode
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 Authentication is performed using the AR System User form. If successful, user information is
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 Authentication behavior
mode
All Authentication chaining

modes Authentication is performed using OS authentication. If successful, user information is
retrieved from the OS.
If OS authentication fails, authentication processing stops.
User exists with no password in User form

Authentication chaining Authentication behavior
mode
All Authentication chaining

modes Authentication is performed using OS authentication. If successful, user information is
If OS authentication fails, authentication processing stops.
User exists with password in User form

chaining mode
Off
If BMC Remedy AR System authentication fails, authentication processing stops.


chaining mode
ARS - AREA
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
ARS - AREA - OS
Setting up the AREA hub

The BMC Remedy AR System plug-in server supports only one AREA plug-in directly. You can,
however, add a single AREA Hub plug-in to the plug-in server and then add multiple AREA plug-
ins to the AREA Hub plug-in. Plug-ins you add to the AREA Hub are referred to as Hub-plug-ins.
The AREA Hub propagates the calls it receives from the Hub-plug-ins to the Plug-in server.
The AREA Hub loads the Hub-plug-ins in the order in which they appear in the ar.cfg or ar.conf
file. That is, the first entry the AREA Hub finds in the ar.cfg file is the first plug-in loaded, the
second entry the second, and so on.
Notes
You do not need to configure the AREA Hub manually to use multiple AREA LDAP
plug-ins. See Configuring the AREA LDAP plug-in (see page ).
The AREA hub works only with DLLs. Java plug-in server has an inbuilt capability
to chain across multiple Java AREA plug-ins. So, you do not need AREA hub for
Java. You can configure multiple AREA Java plug-ins in pluginsvr_config.xml

To set up the AREA hub plug-in
1. Create the following entry for the AREA hub in the ar.cfg file:
Plugin: areahub.dll
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 (see page ).
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

2.
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 in BMC
Atrium Single Sign-On online documentation.
Data and database integrations

This section contains information about data and database integrations:
Creating vendor forms (see page 838)

View forms (see page 840)
SQL database access (see page 848)
ODBC database access introduction (see page 850)
Creating vendor forms

In this topic:
Vendor forms introduction (see page 838)

To create a vendor form using an ARDBC plug-in (see page 839)
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 (see page ).
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 (see page ).
The vendor form can be manipulated as a regular form type with the following exceptions:
You can add only Required and Optional fields that correspond to actual columns in the
data source. In addition, you can add a Display Only field only when the column name does
not correspond to a column in the data source.
To create a vendor form using an ARDBC plug-in
1. In BMC Remedy Developer Studio, choose File > New > Vendor Form.
The New Vendor Form Wizard appears.
2. Select the server on which you want to create the vendor form, and click Next.
3. Select the ARDBC plug-in to use in the list of Available Vendor Names, and click Next.
4. Choose a table from the list of Available Vendor Tables and click Next.
Alternatively, type a table name in the Table field, click Validate, then click Next.
5. (optional) On the Field Selection page, choose a key column in the Key Field list box.
The key column uniquely identifies the entries in your vendor form. Key values are mapped
to the Request ID field on the Vendor Form.
6. In the Available Columns list on the Field Selection page, select columns to access in BMC
Remedy AR System. Use the arrow buttons to move them to the Selected Columns list.
New Vendor Form Wizard, Field Selection page

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 (see page 2382).
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 (see page 841)

Database data types for view forms (see page 844)
Database requirements for view forms (see page 846)
Field properties on view forms (see page 847)
Setting up a remote database for view forms (see page 848)
Creating and modifying view forms

Use BMC Remedy Developer Studio to create and modify view forms.
In this topic:
Mapping an alternative AR System field type (see page 843)

Modifying view forms (see page 843)
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 (see page ).
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.
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.
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 (see page 841), but in step 7
(see page 842), 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:
DB2 data type mapping for view forms (see page 844)
SQL Server data type mappings for view forms (see page 845)
Oracle data type mappings for view forms (see page 845)
Sybase data type mappings for view forms (see page 845)
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 (see page 843).
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 (see page 2047).
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

DB2 data types AR System field type
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 AR System field types

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)

Sybase data types AR System field types
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:
DB2 considerations for view forms (see page 846)

AR System requirements for view forms (see page 847)
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 (see page ).
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 System
Configuration Generic UI form by using the Db-user option. For example, if the DB2

administrator's name is db2admin, add the following line to the AR System Configuration
Generic UI form:
Db-user: db2admin
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
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 (see page 849)

Pulling data into BMC Remedy AR System with SQL (see page 849)
Pushing data from BMC Remedy AR System with SQL (see page 850)
SQL database considerations (see page 850)
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
(see page 2019).
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 (see page 3636).

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 (see page 2827).
SQL database considerations

Consider the following issues when working directly with an SQL database:
The AR System server typically has full administrator access to the database for reading
and writing any data. AR System users have permissions to read and write specific data
using an AR System client, and these permissions are managed by the AR System server.
If users access the database directly through a database client, they are bypassing the AR
System security model.
BMC Remedy AR System stores some data in the database in formats that can cause third-
party applications to become confused. For example, AR System date/time fields store
values as timeticks, which are the number of seconds from 1 January 1970 at midnight until
the current time. These numbers are stored as integer numbers, and typically need to be
converted by the third-party application.
All SQL commands are sent to the database server that holds the AR System database. To
access databases that are external to this DB server, you must have the appropriate conduit
installed and issue the SQL commands needed to use the conduit for your SELECT
statement.
ODBC database access introduction

The Open Database Connectivity (ODBC) standard is a connectivity solution that enables ODBC
clients to communicate with BMC Remedy AR System. The AR System ODBC driver provides
read-only access to data defined in AR System forms. This section discusses the use of the AR
System Open Database Connectivity (ODBC) driver to provide additional functionality with other
programs.
ODBC is an SQL-based communication standard developed by Microsoft. The ODBC standard

represents a connectivity solution that enables ODBC clients to communicate with BMC Remedy
AR System. The AR System ODBC driver provides read-only access to data defined in AR System
forms.
The interface provided by the ODBC driver (arodbc70.dll) is similar to that provided by the AR
System API. Like the API, the driver does not provide access to the underlying relational database.
Instead, as shown in the following figure, the driver communicates with the AR System server,

which in turn communicates with the database server. When using the ODBC driver, the AR
System access control model (user and group permissions) is maintained, and server-side
workflow is still triggered.
ODBC integration
Many ODBC clients are available. The AR System ODBC driver provides extended functionality
with BusinessObjects Crystal Reports. In addition, the driver provides basic functionality with
Microsoft Access, Microsoft Excel, and other ODBC clients. See Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation for additional information about supported ODBC
clients.
BMC Remedy AR System ODBC considerations (see page 851)

Compatibility with ODBC clients (see page 852)
Creating an unqualified search in Microsoft Excel with BMC Remedy AR System (see page
852)
Creating multiple data sources (see page 853)
Integrating Crystal Reports with BMC Remedy AR System (see page 855)
Tips for using Microsoft Access with BMC Remedy AR System (see page 861)
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 Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation.
Creating an unqualified search in Microsoft Excel with BMC Remedy AR System

When you create an unqualified search for a diary field in Microsoft Excel, the data appears with
small control characters that appear as small boxes.
To remove the control characters
1. Highlight the cells and choose Data > Text to Columns.

2. Select the Delimited option, and click Next.
3.
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. 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 (see page
).
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.
Using field labels or database names in Crystal Reports (see page 859)

Verifying fields defined in a Crystal Report (see page 860)

Changing the AR System ODBC configuration (see page 860)
Selecting report fields in Crystal Reports (see page 860)
Generating tables from multiple tables (see page 861)
Crystal Reports considerations (see page 861)
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 (see page ).
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 (see page ).
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 (see page 853).
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 (see page 856).
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
(see page 853).

Table names that are nearly identical, such as My.Table and My Table (names that include
decimal points, hyphens, and spaces), are not differentiated by the driver.
Searching for data in these tables might produce unexpected results. Rename table and
field names that are nearly identical.
Maximum size of an entry or data set in Microsoft Access is 2K.
If you encounter the errors Record too large when using the Import Table option or This
form or report is based on a query that exceeds the limit for data in a single record
when using the Link Table option, you must exclude unnecessary fields from the search or
report. See your Microsoft Access documentation for additional information about excluding
fields.
Your Microsoft Access authorized signature and your AR System user name and password
might conflict.
If you notice that the tables or fields disappear (although you have access permissions)
when you work on reports, it is caused by a login identification conflict. To resolve this
problem:
Select the same user name and password that you use to log in to AR System.
Turn off the following flag in the Registry and set the value to 0:
HKEY_LOCAL_MACHINE\Software\Microsoft\Jet\3.5\Engines\ ODBC\TryJetAuth
When using Microsoft Access to link tables from an AR System ODBC data source, you
enter information into several dialog boxes. Do not select any options from the Select
Unique Record Identifier dialog box. Click OK to close that dialog box.
Extending BMC Remedy Developer Studio

Developer Studio is composed of Eclipse plug-ins, which are modules of code that perform various
functions. Some of these plug-ins have public extension points, which are ports through which they
expose their functionality to other plug-ins and indicate which class or method to call to use that
functionality. To add functionality to Developer Studio, you can create custom plug-ins with
extensions that hook into these extension points. Through these connections, custom plug-ins can
exchange API calls with Developer Studio and the AR System server.
Important
To create plug-ins for Developer Studio, you must be familiar with Eclipse plug-in
development (see http://www.eclipse.org) and Java (see http://www.oracle.com
/technetwork/java/index.html). Although BMC Customer Support is available to answer
questions about BMC plug-ins and APIs, it cannot provide help with general Eclipse and
Java issues that you encounter while developing custom plug-ins.
This section contains information about adding custom functionality to BMC Remedy Developer
Studio:

Creating plug-ins to extend BMC Remedy Developer Studio (see page 863)
Prerequisites for creating plug-ins (see page 866)
Extension points for BMC Remedy Developer Studio (see page 866)
Developer Studio Java API (see page 867)
Installation directory for the BMC Remedy Developer Studio plug-ins (see page 867)
Note
This feature does not apply to BMC Remedy AR System release 7.5.00 or earlier.
Creating plug-ins to extend BMC Remedy Developer Studio

Using the public Developer Studio plug-in extension points, you can create plug-ins that extend its
user interface as follows:
Add custom server object types to the All Objects list in AR System Navigator and to object
lists in the Object List tab. For example, the following figure shows an All Objects list that
contains a custom Hamburgers server object at the bottom of the list.
Customized All Objects list in AR System Navigator

When users double-click the custom object type, an object list for that type opens and
displays a list of objects supplied by the custom plug-in (see the following figure).
Customized object type in the Object List tab
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 (see
page 3278).)
Prerequisites for creating plug-ins

To create plug-ins for BMC Remedy Developer Studio, you need the software and project
dependencies listed in this topic.
Software requirements for creating plug-ins
BMC Remedy Developer Studio release 7.6.02 or later

Java SE JDK 1.5 or later
Eclipse for RCP/Plug-in Developers (Ganymede 3.4 SR2 or later for Windows)
To download the Eclipse software, go to http://www.eclipse.org/downloads/packages/release
/ganymede/sr2.
Extract the downloaded ZIP file into C:\Eclipse3.4 (or later version).
Project dependencies for creating plug-ins

Add the following BMC Remedy Developer Studio plug-ins as dependencies to your custom plug-in
project:
com.bmc.arsys.studio.api (7.6.02 or higher)

com.bmc.arsys.studio.commonui (7.6.02 or higher)
com.bmc.arsys.studio.model (7.6.02 or higher)
com.bmc.arsys.studio.ui (7.6.02 or higher)
com.bmc.arsys.studio.analyzer.core (7.6.02 or higher)
To do this, extract the contents of the ARSystemServerInstallDir\ DeveloperStudio\files\Plugins.

zip file into your top-level Eclipse directory.
For example, if your top-level Eclipse directory is C:\eclipse, extract the contents into C:\eclipse.
Extension points for BMC Remedy Developer Studio

The BMC Remedy Developer Studio plug-ins provide these extension points:
Plug-in Description
com.bmc.arsys. Registers new server object types with the AR System Navigator. Examples of server object types are
studio.model. active links, filters, and forms.
modeltype

Plug-in Description
com.bmc.arsys. Registers providers for new object types. For example, list providers supply a list of objects and object
studio.model. providers supply actual objects for editing. The providers can supply items to both the AR System
modelprovider Navigator and the Object List tab.
com.bmc.arsys. Adds actions to context menus in the Object List tab for a single object type. For example, see
studio. Customized context menu for the Active Link object type (see page 865).
commonui.
typeaction
com.bmc.arsys. Adds actions to context menus in the Object List tab. The actions can appear on menus for one or more
studio. object types.
commonui.
genericaction
com.bmc.arsys. Registers new server object types with the user interface to add the types to the AR System Navigator
studio. (see Customized All Objects list in AR System Navigator (see page 863)) and the Object List tab (see
commonui. Customized object type in the Object List tab (see page 864)). It also provides the name of the object type
typeinformation to display in the AR System Navigator.
com.bmc.arsys. Adds rules for the Developer Studio Analyzer command.

studio.
analyzer.core.
analyzerRules
Developer Studio Java API

To incorporate additional functionality--such as information about AR System objects and
workflow--into custom plug-ins, use the public Java API calls in the com.bmc.arsys.studio.model
plug-in.
These calls are described in the Developer Studio Java API online documentation, which is in the
DevStudioInstallDir\files\DevStudioAPIdoc.zip file.
To access the documentation, unzip the file, and open the index.html file.
Installation directory for the BMC Remedy Developer Studio

plug-ins
To integrate a custom plug-in with BMC Remedy Developer Studio, put the plug-in's .jar file in the
ARSystemInstallDir\DeveloperStudio\plugins directory.
BMC Atrium Orchestrator integration

BMC Atrium Orchestrator (Atrium Orchestrator) enables IT organizations to automate tasks and
processes, such as trouble ticketing, fault management, performance monitoring, virtualization
management, and so on.
This section describes how to configure BMC Remedy AR System for integration with Atrium
Orchestrator. To use the information in this chapter, you should be familiar with creating forms and

workflow in BMC Remedy AR System, and you should understand how to use the Set Fields action
in a filter or escalation. You must also be familiar with Atrium Orchestrator processes and
operations.
Note
To integrate BMC Remedy AR System with Atrium Orchestrator, you must use BMC
Atrium Orchestrator 7.5 or later. For a list of the compatible web application servers, see
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation. For
more information about Atrium Orchestrator processes and operations, see your Atrium
Orchestrator documentation.
Application developers can integrate AR System applications with Atrium Orchestrator. This
integration requires the AR System Web Services plug-in, which uses the Java plug-in server, to
be installed with the AR System server. BMC Remedy AR System acts as a consumer of the
Atrium Orchestrator web service.
Note
The AR System API files arutil-7.5.00.08.jar and arapi-7.5.00.08.jar bundled with the
BMC Remedy AR System adapters does not work with the BMC Remedy AR System
version 9.0, and causes the integration between BMC Atrium Orchestrator and BMC
Remedy AR System to fail. For more information, see Troubleshooting the BMC Remedy
AR System adapter in the BMC Atrium Orchestrator online documentation.
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 (see page
2242). For information about using Development Studio with Atrium
Orchestrator processes, see the Atrium Orchestrator documentation.
Defining BMC Atrium Orchestrator web services (see page 869)

Modifying entries in the AR System Orchestrator Configuration form (see page 871)
BMC Remedy AR System workflow for BMC Atrium Orchestrator integration (see page 872)
Obtaining job status for asynchronous execution operations (see page 875)
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 (see page 872).
The following figure shows an example of a completed entry in the AR System

Orchestrator Configuration form.
Example AR System Orchestrator Configuration form entry

Modifying entries in the AR System Orchestrator Configuration

form
Information stored in the AR System Orchestrator Configuration form is used at design time when
you create filters and escalations to perform Atrium Orchestrator operations. When you save the
filter or escalation, information from the configuration form is stored in the workflow object.
If you change the information for a configuration entry after associating workflow to the
configuration, Developer Studio prompts you to confirm whether you want to override the
information stored in the filter with the new information from the configuration form.
Overwrite dialog box
As shown in the Overwrite from configuration form dialog box, the active fields are those that have
different values in the configuration form entry from those stored in the workflow. To override these
values in the workflow object with the values from the configuration form, select the appropriate
check boxes. (If the check box is inactive, that value has not changed.) When you save the filter or
escalation, the new values are saved with it.
Note
If you export the Atrium Orchestrator workflow and import it to another AR System server,
you should also export and import the associated entry in the AR System Orchestrator
Configuration form. This entry is needed if the filter or escalations that use it are to be
edited on the other server. If you do not export the configuration form entry, you can still
run the workflow on the other server.

BMC Remedy AR System workflow for BMC Atrium

Orchestrator integration
To integrate an AR System application with BMC Atrium Orchestrator, use Developer Studio to
create an AR System form or forms to hold the input and output data for each process, and a filter
or escalation to exchange information with BMC Atrium Orchestrator.
In the AR System filter or escalation, you select the BMC Atrium Orchestrator processes and the
operation to perform. The workflow can be designed to carry out either synchronous or
asynchronous BMC Atrium Orchestrator operations. With synchronous execution, BMC Remedy
AR System waits for the operation to complete before returning a result to the workflow action.
With asynchronous execution, the operation returns a job ID. In this case, you use the job ID in
subsequent workflow actions to determine the status of the operation, or to cancel it.
Note
You must use a separate Set Fields action for each BMC Atrium Orchestrator process.
To define the application form
1. Create a regular form, and add the appropriate fields to hold the input and output data for
the Set Fields action.
The input and output fields on the form depend on the operation and process type. You can
create one form that will hold the data for all process integrations, or separate forms for
each process.
2. Save the form and assign a form name.
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 (see page
).
5. To add a BMC Atrium Orchestrator process to the Process table, click Add.
6.
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.
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.
Running external processes with the Run

Process action
Run Process actions can be used for integration on both the BMC Remedy AR System clients and
servers.
Running external processes introduction (see page 876)

Triggering Run Process on clients and servers (see page 877)
Starting applications with the Run Process action (see page 877)
Retrieving data from applications with Run Process (see page 880)
Using Run Process for the web (see page 883)
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 (see page ).
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 (see page 2864).
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.
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.
Calling a pager application from a filter scenario (see page 879)
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.
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.
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$


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
(see page 2242) section.

Integrating the BMC Remedy Assignment

Engine into an application
This section explains how to integrate the BMC Remedy Assignment Engine with your application,
starting with the following overview of the process.
To integrate the BMC Remedy Assignment Engine with your

application
1. Create a form that holds the assignees, and add the appropriate Assignment Engine fields
to this form. See Preparing for the auto-assignment process (see page ).
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 (see page ).
3. Create or add the assignee and request forms to the Assignment Engine. See Adding
assignee and request forms (see page ).
4. Create rules for assignments. See Adding assignment rules (see page ).
5. Create processes for assignments. See Adding assignment processes (see page ).
Preparing for the auto-assignment process (see page 885)

Adding fields to the assignee and request forms (see page 886)
Adding assignee and request forms (see page 887)
Adding assignment rules (see page 891)
Setting sequencing for rules (see page 892)
Adding and executing assignment processes (see page 893)
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 (see
page 886).
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 (see page
887).
Hide the fields that you do not want users to see.
Adding fields to the assignee and request forms

The following topics provide information about the fields on the assignee and request forms.
Adding fields to the assignee form (see page 886)

Adding fields to the request form (see page 887)
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 (see page 2600).
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.
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.
4. In the Form Name list, select the assignee form for which you want to build the assignment
process.
5. In the Display Name field, enter a display name for the form you selected.
The display name appears in the Form Name column on the Forms tab and in the
Assignee Form list on the Assignment Rule form.
6. For Form Type, select Assignee form.
7. In the Status list, select Active.
If you do not want to use the form at this time, select Inactive.
8. Optionally, specify a Localefor this assignment form.
Note
If the Localize Server option on the Advanced tab of the AR System

Administration: Server Information form is not selected, all records appear,
regardless of the client's locale. If it is selected, some rules apply. See Setting
performance and security options (see page 285) and Setting the Localize Server
option (see page 3197).
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 (see page 886).
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.

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 the option is selected, some rules apply. See
Setting performance and security options (see page 285) and Setting the Localize
Server option (see page 3197).
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 (see page 887).
Request Form Fields tab

12. Click Save.
Adding assignment rules

All assignment processes must have rules. A process can have multiple rules in sequential order.
Because assignment processes can share rules, modifying a rule affects all assignment processes
associated with it.
Note
Unrelating a rule from a process removes its relationship with that process but retains the
rule for other assignment processes.
To add an assignment rule

2. Click the Rules tab.
3.
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 (see page ).
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.
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.

4.
If no rules are defined for the process, click Create to create rules (see Adding
assignment rules (see page )). Select the rule to reorder.
5. Use the arrow keys to order the rules in the sequence in which you want the Assignment
Engine to use them.
6. Click Save and Close.
Adding and executing assignment processes

After you set up the assignee and request forms, you can add and execute assignment processes.
To add an assignment process

2. Click the Processes tab, and click Create.
The Process Definition form appears.
3. In the Process Name field, enter a descriptive name for the process.
Note
BMC recommends that you use unique process names.
4. In the Request Form field, select a form that creates the requests to which you want to
assign users.
5. (Optional) Enter a description of the process.
6. Click Create to create a rule.
See Adding assignment rules (see page ).
7. Specify a sequence for the rules.
The rules apply according to the order in which they appear. See Setting sequencing for
rules (see page ).
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 (see page 893) through 9 (see page 893).

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 (see page 2871).
For information about creating workflow, see Defining workflow to automate processes (see page
2720).
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.
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 (see page 535) and Setting up DSO to synchronize data
across multiple AR System servers (see page 1796).
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 (see page 2375).

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.
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.
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 (see page 1804).
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
(see page 1847) to avoid the looping issue.
Recommendations for using DSO with BMC Atrium CMDB

The most effective use of DSO in this solution is for incrementally updating the CMDB. Generally,
the CMDB is initially populated by a full load before the system goes live. After the full load is
completed, the database containing the fully populated CMDB can be physically copied to the
remote site so the two sites start with an identical image of the CMDB. This reduces the need to
copy potentially millions of CIs all at once.
After the system goes live, the CMDB is periodically updated to include new or changed CIs that
are identified in the IT environment by discovery sources. The number of CIs involved in the
incremental updates is typically much smaller than the total number of CIs in the CMDB. For
example, a site whose CMDB contains roughly one million CIs might have daily updates that
involve 0.1% to 1% of those CIs, which means 1,000 to 10,000 CIs need to be transferred by DSO.
Larger daily updates are possible, particularly if software distribution and patching are done
automatically across the enterprise, but they are much less common.
Timing of the DSO transfers should be considered within the context of overall operational planning
for the CMDB. Specifically:
Discovery scans are scheduled as the source for new and changed CIs.
Reconciliation jobs are scheduled to synchronize the production dataset with new discovery
data.
As the production dataset is updated, the DSO Distribution Pending queue accumulates
pending push operations.
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 (see page

536) on both servers. No asset, however, should be discovered by both sites. Because data is
transferred after it has been reconciled, if both sites try to write to the same CI, the CI might be
updated with different values by each site. The two sites will most likely discover identical
information about the CI.
Therefore, as a best practice, BMC recommends that multiple sites should conduct local discovery
in nonoverlapping domains.
Performance considerations
By default, DSO runs as a single-threaded process writing to remote AR System forms. Excluding
network latency and bandwidth constraints, such an operation has throughput similar to other such
write operations (approximately for 10 DSO pools, 21 CIs per second in BMC Atrium CMDB 8.0
with BMC Remedy AR System server 8.0).
To achieve higher throughput, you must use DSO pools, which are essentially independent sets of
DSO activity that can be processed in parallel. For CMDB data, however, both component CIs and
relationship CIs (sometimes called relationship items or RIs) must be transferred, and a
relationship CI cannot exist until its endpoints are created. Therefore, in DSO pools, make sure
that all relationship CIs are created after their associated component CIs . This is best achieved by
making sure that all data from a computer system is in one DSO pool (data from a computer
system should not span multiple DSO pools). However, this might not work if the DSO pool that
handles the endpoint has more load than the DSO pool that handles the relationship instances,
thereby creating a racing condition.
The racing condition can be handled in this way — when the DSO filter for the relationship instance
is triggered, DSO checks whether any endpoint CI is pending for transfer in the pending queue of
the Distributed Pending form. If an endpoint is found in the pending queue, the transfer of the
relationship instance is deferred. The deferred relationship instances are then taken care of by an
AR escalation, which executes at regular intervals and checks all the deferred relationship
instances and performs the same check on endpoint too. During the endpoint check, if the AR
escalation finds that there are no pending endpoints, it triggers the DSO of that relationship
instance and clears the deferred flag. However, if there are pending endpoints, the DSO of the
relationship instance is handled when the next escalation is triggered.
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.

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 Navigating the BMC Remedy
navigate through the BMC Remedy AR System interface AR System interface (see page
901)
Working with searches Running and saving searches

(see page 926)
Creating and managing reports in BMC Remedy AR Reporting on BMC Remedy AR

System System data (see page 943)
Working with approval requests Approving requests (see page

1017)
Working with BMC Remedy Flashboards Using BMC Remedy

Flashboards (see page 1051)
Navigating the BMC Remedy AR System

interface
The following topics provide information about how to navigate the BMC Remedy AR System
interface:
Using the AR System Object List (see page 901)

Opening Approval Central (see page 925)
Copying field information to a new request (see page 925)
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 (see page 2975).

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 (see page 903)
Choosing how forms and applications are displayed (see page 903)
Creating requests (see page 903)
Editing fields with rich text formatting (see page 904)
Modifying requests (see page 919)
Using the query builder widget (see page 920)
How the back button behaves (see page 923)
Opening a form in a new window (see page 923)

Keyboard shortcuts (see page 923)
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:
Note
The RTF options provide a way for you to apply some basic styling of text and to include
images with their text. The options do not provide the level of functionality of a desktop-
based word processor such as Microsoft Word. Functionality will vary among browsers.
Apple Safari browsers support the fewest number of features.
To enable the buttons in the dialog box, type some text or select existing text. Then, you can
format the selected text.
To undo all of the text you entered and formatted in the RTF dialog box, click Cancel or
press the ESC key.
To view text or images in the RTF field without the scroll bars, set the Custom CSS display
property of the RTF field as RTFPanel. Scroll bars appear on the panel that holds the RTF
fields. If the content size exceeds the maximum limits as specified in the display property of
the RTF field, scroll bars appear on the RTF field itself. See Creating and managing fields
(see page 2565) in the Developing the application interface (see page 2373) section.
Note
In the RTF editor, when you select any of the following formatting options and start
typing, the formatting automatically gets applied (without selecting the text.):
Font Name
Font Size
Fore Color
Background Color
To continue with the same formatting on the next line, press SHIFT+ENTER.

When you select a font from the Font Name option, it is not displayed as the
selected item in the drop down immediately, but gets applied.
When you select a font from the Font Name option, though the font gets applied to
the text, the font name is not displayed as selected.
In an unordered (bulleted) list or an ordered (numbered) list, you cannot apply
formatting to a single point in the list. The formatting must be applied to the entire
list.
The ordered or unordered list does not support the indentation option.
The RTF editor supports only one level of indentation.
The following topics provide information about working with RTF fields:
RTF functions (see page 906)

RTF editor shortcut keys (see page 908)
Applying RTF character formats (see page 908)
Adding a table to a character field (see page 909)
Configuring an image for a character field (see page 909)
Inserting and removing URL links in the RTF fields (see page 910)
Creating or updating bookmarks (see page 913)
Using other formatting options (see page 916)
Using the spell checker in the RTF (see page 917)
Updating the spell checker dictionary (see page 918)
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 (see page )
Bold, italic, Make the selected text bolded, italicized, or underlined. Applying RTF character
and underline formats (see page )
Subscript, Select from the character options Subscript, Superscript, and Strike through. Applying RTF character
Superscript, formats (see page )
and Strike
through
Text Color Select the text color from the list. Applying RTF character
formats (see page )
Select the text background color from the list. The options are Red, Blue, Green, Applying RTF character
Black, Yellow, and White. formats (see page )

Button Function See also
Text
Background
Color
Remove Remove all formatting from the selected text. Applying RTF character
Formatting formats (see page )
Show/Hide Select to show or hide the hidden elements.Note: You can use this option only Applying RTF character
Hidden with formatted text. However, if you format the text using Subscript, Superscript, formats (see page )
Elements 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 (see page )
Paragraph Set the paragraph formatting style, including heading tags. Applying RTF character
formats (see page )
Indent Increase or decrease the selected text's distance from the left margin. Applying RTF character
formats (see page )
Bulleted and Create a list formatted with bullets or numbers. Applying RTF character
Numbered list formats (see page )
Create Insert a link to a Bookmark or another website or URL. Inserting and removing
hyperlink URL links in the RTF
fields (see page 910)
Add bookmark Insert a bookmark Creating or updating

bookmarks (see page
913)
Insert image Insert an image into the RTF field. Configuring an image for
a character field (see
page )
Insert Special Use special formatting features, such as a horizontal rule, expandable section, Using other formatting
Items and special characters. options (see page )
Spell Check Runs the spell checker. Using the spell checker
in the RTF (see page
)
Undo and Redo Removes the last 30 changes made in the RTF editor or reverses the undo action.
Cut, copy, and Remove, copy, and paste selected text to and from the clipboard. Applying RTF character
paste formats (see page )
Note: These buttons work only in Microsoft Internet Explorer browsers. For any
other browser, use the shortcut keys listed in the "General RTF shortcuts" (see
page 908) table.
Insert table Insert a table into the RTF field. Adding a table to a
character field (see page
).
Cell Properties Edit the properties of a cell in a table. Adding a table to a

character field (see page
)

RTF editor shortcut keys

The following tables list the keyboard shortcuts that you can use with RTF:
General RTF shortcuts
Shortcut Description
CTRL+A Select all text
CTRL+SHIFT+W Close inner dialog

boxes
SHIFT+CTRL+[ Justify left
SHIFT+CTRL+] Justify right
SHIFT+CTRL+\ Justify center
CTRL+V Paste
CTRL+Z Undo
CTRL+Y Redo
RTF shortcuts that work after text is selected
Shortcut Description
SHIFT+CTRL+Up arrow Increase font size
SHIFT+CTRL+Down arrow Decrease font

size
SHIFT+CTRL+L Create a link
SHIFT+CTRL+A Insert a bookmark
SHIFT+CTRL+B Bold
SHIFT+CTRL+I Italic
SHIFT+CTRL+U Underline
CTRL+C Copy
CTRL+X Cut
Applying RTF character formats
You can apply rich-text formatting to a character field.
1. Click the RTF icon ( ) next to the character field, and select the text to format.
2. Apply the appropriate formatting.
3. To clear the formatting you applied, click Cancel or press the ESC key.
4. Click Save.

4.
Note
You can modify RTF properties for the character fields at run time by using a
workflow. For more information, see Change Field action (see page 2821).
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.
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 (see page 910).
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
new opens the URL. If the check box is not selected, the URL's web page opens on the same browser.
window
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. Move the cursor out of the RTF field.
3. Save the form.
Inserting and removing URL links in the RTF fields

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 (see page 913) 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 (see page 911).
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 (see page 2600).
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 (see page
911), 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 (see page 913)

2. Inserting and removing URL links in the RTF fields (see page 910)
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 (see page 910)
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 >).

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
Inserting and removing URL links in the RTF fields (see page 910)

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.
1. Click in the RTF field, where you want to insert the special character.
2. From the RTF functions toolbar, click Insert Special Items, and select the character from
the list.
3. Click Save.
Using the spell checker in the RTF
To check for spelling errors in the RTF field, launch the spell checker from within the RTF field.
1. From the RTF functions toolbar, click Spell Check.

The spell checker highlights any misspelled words and provides an alternative spelling for
the word in the Replace with box. It also provides additional suggestions in the Suggestions
box.
Spell checker in RTF

2. Correct misspelled words by selecting the new word from the Suggestions box. Other
options in the spell checker window are as follows:
Change Once: Click to change the selected occurrence of the word with the spell
checker suggestion.
Change All: Click to change all the occurrences of the word with the spell checker
suggestion.
Ignore Once: Click to ignore the spell checker suggestions.
Ignore All: Click to ignore every occurrence of the word.
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:
Modifying a single request (see page 919)

Modifying several requests at once (see page 919)
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.
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 entered in the query.
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
(see page 921) through 3 (see page 923) 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:

Panel field shortcut keys (see page 924)

Character field menu shortcut keys (see page 924)
Form action shortcut keys (see page 924)
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 If the focus is on a tab selector (an anchor link), sets focus to the next or previous tab selector without
RIGHT ARROW displaying it. Press ENTER to display the selector.
ENTER If the focus is on a tab selector, displays the page.
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 (see
page 3228).
Character field menu shortcut keys
Key Description
UP or DOWN Moves focus through the menu items. Press ENTER to fill the field with the menu selection.
ARROW
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.

Key Description
CTRL+ALT+H Shows status history values.
CTRL+ALT+S Sets focus to the Advanced Search Bar input field.
CTRL+ALT+C Copies field information to a New Request.
Note
In some browsers, the CTRL+ALT+F2 and CTRL+ALT+F3 shortcuts do not work.

Alternatively, click the New Request and New Search buttons on the toolbar to switch
modes. This is keyboard accessible because you can tab through the toolbar.
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.
Copying field information to a new request

You can now copy information from the fields in an existing form to a form in New request mode in
the mid tier application. The new request contains all the data from the copied request, except
diary fields and attachments. If you want the same attachments, you must save each attachment to
a file and then attach each to the new request.
Also, if you wanted to create a new request but filled a form in Search mode, you can copy
information from the fields of the form in Search mode to a form in New request mode.

To copy information from an existing request to a new request
1. Open an existing request.

2. Press Ctrl+Alt+C.
The window changes to New mode, and fields are populated as in the original request.
3. Add or modify information in the fields for the new request.
Note
You cannot save a request until you add or modify data in the request.
4. Click Save.
To copy information from search mode to a new request
1. Open a new form in Search mode.

2. Instead of clicking New request, add information in the fields.
3. Press Ctrl+Alt+C.
The window changes to New mode, and fields are populated as in the Search mode.
4. Add or modify information in the fields for the new request.
5. Click Save.
Running and saving searches

The following topics provide information about how to save and run searches on the web:
Finding a request by example (see page 926)

Running a saved, recent, or defined search (see page 930)
Loading search criteria without execution (see page 931)
Saving searches (see page 931)
Managing saved searches (see page 932)
Running searches (see page 933)
Types of searches (see page 934)
Using the advanced search bar (see page 934)
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.
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 (see page ).
The following topics provide information about how to find a request by example:
Search styles in character fields (see page 927)

Overriding the predefined search style (see page 927)
Using relational operators and wildcard symbols in a search (see page 928)
Using wildcard symbols as explicit characters in a form (see page 930)
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.
Note
Equal and Leading searches are faster than Anywhere searches because Anywhere
searches compare each character in the field while Equal and Leading searches do not.
Overriding the predefined search style

To override the default search style for a character field, enter exactly what you are searching for in
the field, and include a relational operator or wildcard character.

For example, you can use an equal sign (=) to search for an exact match even if the field has a
search style of Anywhere. Thus, if you enter =Bob Jones in the Created By field of a form, the
search will find all the requests created by Bob Jones. The search will not find requests created by
Bob Joneson.
You can also use the advanced search bar to override a field's search style. For example, to
override the Created By field in the previous example with a Leading search, you would specify
the following criteria in the advanced search bar:
'Created By' LIKE "Bob Jones%"
Using relational operators and wildcard symbols in a search

You can use the relational operators or wildcard symbols in a form and in the advanced search
bar.
Using relational operators in a search

Relational operators are useful in non-text fields (such as date and time fields) when you want to
search for a value within a numerical range.
You can use the following relational operators as leading characters in fields in a form and in the
advanced search bar.
Relational operators
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 Matches any single character within a specified range or set. For example, [a-f] matches the range of
brackets) characters a through f, and [abcf] matches the set of characters a, b, c, or f.
[^] (Square Matches any single character not within a specified range or set. For example, [â-f] matches all characters
brackets with except the range a through f, and [âbcf] matches all characters except a, b, c, or f.
caret)
Use the percent symbol (%) to include leading or trailing characters in your search. For example, to
find all requests submitted by Jill Bobbington, Bobby Fenton, and Bob Comptonson with an
Anywhere search, enter *Bob%ton* in the Submitter field. The search returns all requests for
which the Submitter field contains the strings "Bob" and "ton" in that order with any number of
characters leading, trailing, and in between.
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 (see page
).

Using wildcard symbols as explicit characters in a form

To search for the actual characters that serve as wildcard symbols, you must force the system to
interpret these wildcard characters as explicit characters. For example, you might need to search
for all instances of the percent sign instead of using the percent sign as a wildcard symbol.
To search for the percent sign (%), underscore (_), or open bracket ([) as an explicit character,
enclose the character in square brackets. For example, if you enter the percent sign in square
brackets ([%]), the system searches for instances of the percent sign instead of using it as a
wildcard character.
The close bracket (]) functions as a wildcard only when it is accompanied by an open bracket ([).
The hyphen (-) functions as a wildcard character only when preceded by an open bracket ([) or an
open bracket with a caret ([^).
Running a saved, recent, or defined search

1. From the toolbar, select Searches > Run My Searches, Run Recent, or Run Defined.
Searches menu
2. From the list of searches, select a search to run.

The system executes the search and displays a results list.
Search results

Loading search criteria without execution

You can load search criteria from saved, recent, or defined searches into a form without executing
the search. You can then modify the search criteria, or execute the search as it is.
1. Open a form in Search mode.

2. From the toolbar, select Searches > Load My Searches, Load Recent, or Load Defined.
3. From the list of searches, select the search you want to load into the form.
The search criteria is loaded into the form. You can execute the search by choosing Search
from the toolbar, or you can modify the search criteria.
Saving searches
The following procedure details how to save and run searches from a form that you created viewed
in a browser.
Note
You must execute a search before you can save it.
1. Run a search. (See Running searches (see page ).)

2. From the toolbar, select Searches > Save Search.
The Save or Redefine Search dialog box appears.
3.
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.
Managing saved searches

This section describes how to enable, disable, or delete existing saved searches. Disabling a
search removes it from the list of searches, but keeps the search data.
Enabling or disabling a search
1. From the toolbar, select Searches > Manage My Searches.
Manage Search dialog box

2. In the Manage Search dialog box, select the search you want to enable or disable, and click
the Enable or Disable button.
If a search is not yet selected in the Manage Search dialog box, the default button label of
Disable is displayed.
The state of the search changes to either Enabled or Disabled, depending on your action.
If the search is disabled, it no longer appears in the search menu on the toolbar, but the
search data is still stored in the AR System Searches Preference form.
3. Click Save to save your changes.
Deleting a search
1. Select the search you want to delete.
2.
2. Click Delete.
3. Click Save.
The search is deleted from the list in the Manage Searches dialog box, from the search
menu, and from the AR System Searches Preference form. To restore a deleted search,
you must recreate and save it.
Running searches
You can save searches in a browser and run them at any time by selecting Searches from a
toolbar menu in a form. You can also make recent searches and defined searches available in a
browser. You can load each type of search criteria into a form, and update the search criteria
before you execute a search. You can run all searches across multiple sessions.
Methods for running searches
You can run a search using any combination of the following methods:
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 (see page ).
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 (see page ).
Parameters — Enter a parameter enclosed in dollar signs ($) in the field. For example, so
that you can specify the submitter each time that you run the saved report, enter the prompt
text $Enter User Name$ instead of a specific name in the Submitter field. When you click
Search, you are prompted to enter a sample value for this parameter. A parameterized
search works best when it is saved. Saving the search enables you to enter different values
each time a search is performed.
To run a search
1. Open a form in Search mode.

2. Enter the search criteria in the form fields, in the advanced search bar, or a combination of
both.
3. Click Search.

Types of searches
The following types of searches are available on the Web:
Saved searches - Searches that you can create and save for a form.
Recent searches - Searches that you have executed recently.
Defined searches - Searches defined by your administrator.
Using the advanced search bar

You can use the advanced search bar to define a more complex set of criteria than you can specify
by using only fields in a form. For example, you can search for all requests with two different
values in the same field. Thus, you could search for all requests that have a status of Fixed or
Closed.
When you specify search criteria in the advanced search bar, you can use the same operators as
in the form, and several more. See Using relational operators in the advanced search bar (see
page ).
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 (see page ).
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.
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 (see page ).)
3. Click Search.
The following topics provide information about how to work with the advanced search bar:
Using fields in the advanced search bar (see page 935)

Using relational operators in the advanced search bar (see page 939)
Using wildcard symbols in the advanced search bar (see page 941)
Examples of advanced search bar statements (see page 942)
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 (see page 935)

Using currency fields (see page 936)
Using keywords in the advanced search bar (see page 936)
Using values in the advanced search bar (see page 939)
Using selection field values (see page 939)
Using currency field values (see page 939)
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 (see page ).
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 !

Operator Action
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 (see page 2030) and the Operators (see page 2783).
+
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 To match these characters:

wildcard:
% (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 Matches any single character within a specified range or set. For example, [a-f] matches the range of
brackets) characters a through f, and [abcf] matches the set of characters a, b, c, or f.
[^] (Square Matches any single character not within a specified range or set. For example, [â-f] matches all characters
brackets with except the range a through f, and [âbcf] matches all characters except a, b, c, or f.
caret)
In the advanced search bar, wildcard symbols are interpreted as wildcards only when used with the
LIKE operator; otherwise, they are interpreted as explicit characters. You must use the percent
symbol (%) when you want to include leading or trailing characters in your search. For example, if
you want to find all requests submitted by Jill Bobbington, Bobby Fenton, and Bob Comptonson,
enter the following text in the advanced search bar:
'Submitter' LIKE "%Bob%ton%"
Note
Square brackets and the symbols associated with them do not work with Oracle
databases.

Examples of advanced search bar statements

The statements in the following examples illustrate ways you can use the advanced search bar to
build complex searches.
Finding all requests that were created by someone other than the current user
Enter
'Submitter' != $USER$
This example uses the not equal to operator (!= ) to find instances where the value in the Submitter
field is not equal to the user who is currently logged in. Notice the use of the $USER$ keyword.
Finding all requests that were created after 10:00 a.m. on the current day
Enter
'Create date' > "10:00:00"
The example uses the greater than operator (> ) to find requests where the value of the Create
date field is greater than the current day at 10:00 a.m.
Finding all requests that have been created for any problem that involves printing
Enter
'Submitted Problem Type' LIKE "%print%"
The example uses the LIKE operator to perform a pattern search that finds requests with the word
print anywhere in the Submitted Problem Type field.
Finding all requests with a status of released

Enter
'Status ' = "Released"
Notice the spaces after the word Status in the field specification. The spaces exist in the field label
on the form being used. If you use the Field List dialog box by selecting the Fields button on the
advanced search bar, the spaces (and single quotation marks) are added automatically.
Note
A search statement that includes a not equal to operator (!= ) might return unexpected
results because the advanced search bar complies with ANSI SQL standards. One of
these standards distinguishes between fields that contain data and fields that have never
contained data.

For example, the following statement does not return requests where CharacterField is empty:
'CharacterField' != "one"
To include requests where CharacterField is empty, enter the search statement like this:
'CharacterField' != "one" OR 'CharacterField' = $NULL$
Reporting on BMC Remedy AR System data

The BMC Remedy AR System Report Console provides a single interface for all Web-based
reporting functions. You can create and run ad hoc reports based on user-specified criteria, and
can also run existing reports that are defined by others or installed with BMC applications.
To open the Report Console, click the BMC Remedy AR System Report Console link in the
Quick Links area of the home page, or click the Report button after running a form search in a
browser. You can also open the Report Console by entering the correct URL to the AR System
Report Console form. BMC Remedy applications provide additional links that open the Report
Console.
The following topics provide information about reporting:
BMC Remedy AR System Report Console (see page 943)

Report designer screen (see page 944)
Report types (see page 945)
Running reports in the Report Console (see page 946)
Creating reports (see page 956)
Editing and deleting reports (see page 971)
Scheduling reports (see page 972)
Publishing reports (see page 973)
Saving or exporting BMC Remedy AR System reports (see page 975)
Using a BIRT editor to create or modify web reports (see page 976)
The following topics provide information about report permissions:
Running reports (see page 947)

Setting permissions for a report (see page 971)
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 (see page ).
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 (see page )

Running reports (see page )
Adding to or overriding a report query at runtime (see page )
Reporting based on a search (see page )
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 (see page )

Creating a Web chart report (see page )
Using a query in a Web report (see page )
Defining BMC Remedy AR System reports (see page )
Report types
The options available for creating, running, and saving reports vary based on the report type. BMC
Remedy AR System includes these report types:

Web reports — The Web report type provides browser users the ability to create nicely
formatted reports. Results can be returned in the form of a list, many styles of charts, or a
list and chart together. Web reports can contain links that allow you to drill down from the
report to open BMC Remedy AR System records and view the data upon which the report is
based. Web reports can be saved in several standard formats, including Adobe PDF and
Postscript, and Microsoft Word, Excel, and PowerPoint formats.
Web reports are suitable to use in presentations, documents, email, and printing, and can
transfer data directly to spreadsheet format. Also, because each row in the report output
contains a link to the underlying data in the form, you can use Web reports to work
interactively with BMC Remedy AR System data.
BMC Remedy AR System reports — You can use BMC Remedy AR System reports to
generate output in several standard formats, including XML, .arx, and comma-separated
value (.csv). BMC Remedy AR System reports are typically used to export data in the
specified format for use in another application, for importing data into another BMC Remedy
AR System server, and to generate statistics based on the report data.
Crystal reports — Some installations of BMC Remedy AR System are integrated with the
SAP BusinessObjects or Crystal Reports reporting tools. If your administrator has installed
one of these products and has designed Crystal reports for use with BMC Remedy AR
System, you can run Crystal reports from the Report Console.
Running reports in the Report Console

The following topics provide information about how to use the Report Console to run existing
reports:
Finding reports (see page 946)

Running reports (see page 947)
Exporting or printing Web reports (see page 948)
Opening the records in a Web report (see page 950)
Exporting BMC Remedy AR System reports (see page 951)
Adding to or overriding a report query at runtime (see page 952)
Adding or modifying a qualification at runtime (see page 952)
Reporting based on a search (see page 954)
Using the My Reports toolbar button (see page 955)
For information about creating reports, see Creating reports (see page ).
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 (see page ).
Warning
If the report includes a primary and secondary form, the filter shows only fields that
are included in the primary form.
3.
3. (Optional) To override a built-in report query, click Override. See Adding to or overriding a
report query at runtime (see page ).
4. For BMC Remedy AR System reports only, select the output format before running the
report. See Exporting BMC Remedy AR System reports (see page ).
Web reports run in HTML and you select the output format after running the report. See
Exporting Web reports (see page ).
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 (see page ).
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 (see page ).
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:
Show Additional Filter to narrow the report results

Override to override the built-in query to widen or change the report results.
If the edit icon ( ) appears next to a report entry in the Report Console, you can open the
report definition to examine the built-in query.
The Adding or modifying a qualification at runtime (see page 952) 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 (see page 973).
This topic includes:
To add or modify a qualification at runtime using Show Additional Filter and Override (see
page 952)
Restrictions on modifying qualifications at runtime (see page 953)
Examples for modifying qualifications at runtime (see page 953)
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 (see page ).
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 (see page ).
2. Run a report based on the search results. See Reporting based on a search (see page )
.
3. Close the report.
4. In the browser window containing the search results, select My Reports > Save.
5. Enter a name for the report, and click OK.
Running a saved report from the My Reports toolbar menu
1. Open the form associated with the report that you saved.
2. Select My Reports > Run > reportName.

Managing reports from the My Reports toolbar menu
1. Open the form associated with the report that you saved.
2. Select My Reports > Manage.
The saved reports appear in a dialog box.
3. Delete, disable, or enable reports as needed.
4. Click Save.
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 (see page 957)

Defining a Web list report (see page 958)
Creating a Web chart report (see page 960)
Types of report charts (see page 961)
Defining a chart report (see page 962)
Using a query in a Web report (see page 963)
Using the simple query builder (see page 964)
Using the advanced query builder (see page 965)
Queries on selection fields (see page 966)
Defining BMC Remedy AR System reports (see page 967)
Specifying fields and sorting criteria for a report (see page 968)
Including statistics in a report (see page 968)
Configuring the page setup in the General section (see page 970)
Specifying which records are in a report (see page 970)
Entering a description for a report (see page 970)
Setting permissions for a report (see page 971)
Specifying the report administrator and status (see page 971)

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. In the Form field, 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 the Forms Used in Existing Reports check box. 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.

5.
Cleared — 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 (see page ).
Defining a Web list report

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 (see page 957).
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 (see page ).
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 also have 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, select 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 (see page ).
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.
Creating a Web chart report
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 (see page 957).
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 (see page ).
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
Maximum — Shows the maximum of the values in the series field for each
Series Field — Select the field to supply the category data for the chart.
In a pie chart, the values in the series field are used to created each "slice" of the pie.
In graphs, the values in the series field are plotted on the Y-axis.
Series Label — Supply a label to appear on the chart that describes the series data.
For example, to produce a chart report based on the Sample:Classes form that
shows number of students enrolled in each class, select the following chart options:
Type — Tube Chart
Category
Field — Class Title
Label — Class title
Series
Aggregation — Sum
Field — Number Enrolled
Label — Total enrolled
4. (Optional) To preview the report before you save it, click Preview.
A sample report runs and appears in a separate browser window.
5. To save the report for future use, click Save.
6. Click Back to return to the Report Console report list.
Using a query in a Web report

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 entered in the query.
Is not equal to — Selects records in which the value in the chosen field does not
match the value entered in the query.
Is empty — Selects records in which the chosen field is empty.
Is not empty — Selects records in which the chosen field contains some data.
Is myself — Selects records in which the value in the chosen field matches the
current user's login ID.
Is not myself — Selects records in which the value in the chosen field does not
match the current user's login ID.
Is LIKE — Selects records in which the value in the chosen field matches the string
defined in the query.
The LIKE operator requires that you use the percent (%) wildcard, which matches
any string of 0 or more characters. For example, to get a report of classes for which
Teresa Logan is the instructor, use one of the following search strings:
Teresa% matches all entries that begin with "Teresa"
%Logan matches all entries that end with "Logan"
T%eresa% would find entries that start with "Teresa" or "Theresa"
4. Type the value to search for in the blank field.

For example, to find Teresa Logan's classes that have students enrolled, you could use the simple
query builder to construct the following query:
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 (see page ).
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 (see page ).
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 (see page 957).
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 options 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,

5.
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.
You can click Remove to remove a selected field or click Remove All to remove all
selections from the field list.
5. Click Modify to update the selected field label or width specification.
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.
1. From the Operation field, select the appropriate operation:

Count — Tallies the number of requests.
Sum — Adds up specified fields or the arithmetic relationship among fields.
Average — Calculates the average of specified fields.
Minimum — Calculates the minimum value for a specified field.
Maximum — Calculates the maximum value for a specified field.
Except for Count, these operations can be applied only to numeric and date/time
fields. Each operation can apply to the whole report, or to a group of requests in a
report. Groups are defined in the Sorting tab.
2. From the Expression field, select a field from the menu list to include as part of a statistic.
An expression is required for all statistical operations except Count. Whether you include an
expression for a Count operation depends on how you want rows with null values to be
counted.
If you are defining a Count operation that includes an expression, only rows with a value
that is not null for the specified expression are counted when the report is run. If you are
defining 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 (see
page 2788).
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

3.
\n Return
\t Tab
\ Backslash
\nnn ASCII
character
4. From the Compute On field, select the scope of a statistic.

You can determine whether a statistic is calculated for the entire report, or for defined
groups within the report by selecting the appropriate setting in the Compute On field.
Report — Calculates the statistic for all entries in the report. The statistic appears at
the end of the report.
Group N — Calculates a statistic for groups defined in the Sorting tab. The statistic
appears below each group.
5. In the Layout field, for the Windows platform only, specify how you want the results to be
displayed in the report by choosing one of the following options:
Single — Displays all the statistical results on one line.
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 (see page
).
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:
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.
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.
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
(see page ).
5. Click Back to return to the Report Console list.
Deleting an existing report
1. Select the report in the Report Console.

2. Click Delete .
Scheduling reports
An administrator can assign the Job Scheduler role to groups so that members can create or
modify a schedule that specifies when a report listed in the Report Console is run and published
(called report scheduling).
Note
Only administrators can schedule reports.
Prerequisites for scheduling reports

To schedule reports you must have Job scheduler role in your role list.
1. On the BMC Remedy AR System Administration Console, open the Roles form and search
for Role name as Job Scheduler.
2. In the Production field, select the Reporting User group.
3. Open the User form and assign the Reporting User to the Group List field.
4. Login to BMC Remedy AR System and verify if the user has the permission to publish
/schedule Web reports.
For more information on scheduling reports, see the following section.
To schedule reports
1. In the Report Console list, locate the report that you want to publish.
2. Select the report and click Schedule.
3. If a schedule has not been defined for the report, click New to create a schedule for
publishing a report.
4.
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 (see page
).
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 (see page ).
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.
3. In the AR System Report Schedule UI dialog box, select the file type for the report from the
Export options list. For example, PDF, Word, HTML, PowerPoint.
Note
If you use the HTML option, images and charts in a report are not rendered.
4. In the Send report to field, enter the email ID, login ID, login name, or email address of the
recipients to distribute the report.
Note
Use semicolon (;) to separate the email IDs.
In the Send status to field, enter the email ID, login ID, login name, or email address of the
recipients to provide information about the report status or errors that might occur while
publishing the report.
5. In the Qualification to Usefield, use or modify the external qualification that was entered
when searching the form data. If you modify the qualification, by copying it from the Report
Console or the advanced search bar, it overrides the qualification from the initial qualified
search. If this field is empty, the embedded report qualification is used.
Note
The Qualification to Use field does not appear when publishing or scheduling a
report from the Report Console instead of performing a form search. It also does
not appear after an unqualified form search or after editing an existing schedule
with a pre-saved empty qualification.
6. Click Finish.
Example of modifying a qualification when scheduling a report

Bob, a manager for the training program, creates an ad-hoc report by selecting the Sample:
Classes form and running a search. Bob saves the qualification in the report by adding a built-in
qualification. If Bob schedules and publishes a report from the search results, the Qualification to
Use field shown during scheduling uses his search qualification, which overrides his built-in
qualification. Chris, a different training program manager, runs a different search on the Sample:

Classes form, selects Bob's report, and then creates his own schedule. Dave, another manager,
also runs a different search on the same form, selects Bob's report, and creates his own schedule.
When Chris and Dave create their own schedules, the Qualification to Use field uses their own
search qualifications.
Saving or exporting BMC Remedy AR System reports

You can save or export AR System data to use in AR System forms, in a spreadsheet, or in other
applications. You can also save or export non-AR System data from another application to use in
an AR System form.
The file formats that you select for exporting depend on the original data source and how you will
use the data. File formats for BMC Remedy AR System reports are explained in the following
sections.
The following topics provide information about how to save or export BMC Remedy AR System
reports:
Using AR Export format (see page 975)

Using AR XML format (see page 975)
Using comma-separated values format (see page 976)
Using record, column, and compressed formats (see page 976)
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.
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 (see page 561).
This section provides the following information for using BIRT:
Installing the BIRT Report Designer to work with AR System Web reports (see page 977)
Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences
(see page 978)
Creating a new report with the BIRT Report Designer (see page 980)
Modifying an out-of-the-box Web report with the BIRT Report Designer (see page 988)
Importing a Web report to a different AR System server (see page 991)
Deploying BIRT reports to the AR System server using the Report form (see page 991)
Examples for modifying reports with the BIRT Report Designer (see page 993)
Installing the BIRT Report Designer to work with AR System Web reports
Before you can modify or create reports using the BIRT Report Designer, you must perform the
following high-level steps:
1. Download version 2.5.1 the BIRT Report Designer.

2. Copy three BMC Remedy AR System plug-ins into their proper location.
3. Specify the BIRT library and template location in the BIRT Report Designer.
For information about system requirements for the BIRT Report Designer, see the Eclipse
documentation.

To download and open the BIRT Report Designer
1. Download the BIRT Report Designer 2.5.1 zip file: http://www.eclipse.org/downloads

/download.php?file=/birt/downloads/drops/R-R1-2_5_1-200909220630/birt-rcp-report-
designer-2_5_1.zip.
The BIRT Report Designer is a 32-bit application, and requires a 32-bit Java installation.
2. Extract the BIRT Report Designer zip file to a destination directory (BIRTInstallDir).
3. To open the BIRT Report Designer application, click the BIRT.exe executable file.
To copy BMC Remedy AR System plug-ins for use with BIRT
1. Go to BIRTInstallDir, and create in it a plugins subdirectory.

2. Copy and paste the following plug-ins from your mid-tier plugins directory (MidTierInstallDir
/WEB-INF/platform/plugins) to BIRTInstallDir/plugins:
com.bmc.arsys.oda.designtime_versionNumber.buildNumber.jar
com.bmc.arsys.oda.runtime_versionNumber.buildNumber.jar
com.bmc.arsys.studio.api_versionNumber.buildNumber.jar
3. In the BIRTInstallDir directory, launch BIRT.exe.
The BIRT Report Designer application opens.

Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences (see
page 978)
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.
2. In the Type field, select BIRT Library, and then click Search.
AR System Resource Definitions form

3. In the search results, select BIRT Resource File.

4. In the Resource section, select the Resources.zip file, and click Save to Disk.
5. Go to BIRTInstallDir, and create a Library subdirectory.
6. Copy the Resources.zip file to the BIRTInstallDir/Library directory.
7. In the search results, select BIRT Report Library.
8. In the Resource section, select the BIRT_Library.zip file, and click Save to Disk.
9. Copy the BIRT_Library.zip file to the BIRTInstallDir/Library directory.
10. Create a Resources subdirectory in the BIRTInstallDir/Library directory.
11. Extract the BIRT_Library.zip file into the BIRTInstallDir/Library/Resources directory.
This creates the BIRTInstallDir/Library/Resources/Images and BIRTInstallDir/Library
/Resources/Templates directories. This also places the DateParameter.js and
bmc_library.rptlibrary files in the BIRTInstallDir/Library/Resources directory.
12. Extract the Resources.zip file into the BIRTInstallDir/Library/Resources directory.
This creates the BIRTInstallDir/Library/Resources/Resources directory with *.properties
files as content.
13. Open the BIRTInstallDir/Library/Resources directory, and copy its path.
14. In the BIRT Report Designer, choose Windows > Preferences.
15. In the Preferences box, choose Report Design > Resources, and copy the path for the
Resources directory into the Resources folder field, and then click OK.
Resource panel for Preferences in the BIRT Report Designer


16. 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:
Modifying an out-of-the-box Web report with the BIRT Report Designer (see page 988)
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 (see page 981)
To enable data access for a BIRT report by creating a data source (see page 981)
To define the data available in a report by creating a data set (see page 984)
To preview and save a new BIRT report (see page 988)

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.
1. In the BIRT Report Designer, go to the Data Explorer tab, right-click Data Sources, and
select New Data Source.
Data Explorer pane

2. If the Data Explorer tab is not open, choose Window > Show View > Data Explorer.
3. In the New Data Source dialog box, make sure Create from a data source type in the
follow list (default) and BMC Remedy AR System ODA Data Source (default) are
selected, and then click Next.
New Data Source box


If BMC Remedy AR System ODA Data Source does not appear as a selection in
the New Data Source box, make sure the correct BMC Remedy AR System plug-
in files were copied to the BIRT install directory. See To copy BMC Remedy AR
System plug-ins for use with BIRT (see page ).
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 (see page 981).
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.
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 (see page 991).
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.
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 (see page 993).
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
(see page 990), 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 (see page 988).
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 (see page 994)

Sorting and grouping results by a parameter to organize random results (see page 997)
Adding a column to report results (see page 1000)
Adding a parameter to filter report results (see page 1000)
Editing a Parameter box field to filter report results (see page 1001)
Using subreports to link reports together (see page 1002)

Using dynamic drill down reports to provide a series of detailed reports (see page 1005)
Converting a currency type with a computed column (see page 1011)
Grouping results in multiple groups by using grids (see page 1011)
Using a stacked bar chart to compare different series of results (see page 1016)
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.
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 (see
page 988).
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 of the new child table.

10. Bind the key field of the parent data set to the parameter of the child data set parameter.
Binding tab of the child table
11. Click Data Set Parameter Binding.

12. Bind the parent key value to the child.
Data Set Parameter

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 (see page 1005)

To create a drill down report that links to an incident record (see page 1009)
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.
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. 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.

1.
Viewing the report in the Layout tab

2. Save and run the report to preview it.

3. In the Layout pane, add a column (see page 1000)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. 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

10.
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.
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. 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. Under In the Value (Y) Series, configure at least two series of data for Status using
the Expression Builder.
Optionally, configure the Aggregate Expression field to Count.
c. Under In the Value (X) Series, configure a series of data for Assignee Groups using
the Expression Builder.
If the bar chart needs adjustment, click the Binding tab in the Property Editor for the chart
and review the data binding settings.
Approving requests
The following topics provide information about how to approve requests:
Approval notification through email (see page 1018)

Configuring the Request ID link on Approval Central (see page 1022)
Setting previews for approval requests (see page 1023)
Processing approval requests (see page 1024)
Using the Get Agreement sample application (see page 1043)

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:
Configuring AR System server and email (see page 1019)

Customizing the template (see page 1020)
Defining notifications (see page 1021)
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 (see page 685)
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.
6. In the Add Attachment window, select the template saved in step 3 (see page 1020) 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. (see page 1658)
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 (see page 1020) in Customizing
the template (see page 1020).
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

5.
a.
Email or User Default notify mechanism in a Notify filter action.

The menus in the Fields columns on this tab contain fields from the three-way join
form. You can select from the Fields and Keywords menus to use variables in all the
fields on this tab.
b. In the Mailbox Name field, enter the name of an outgoing mailbox that is configured
in the AR System Email Mailbox Configuration form. This field is not required if you
use the default outgoing mailbox.
You can use a field or a keyword to get the mailbox name. The mailbox name must
correspond to an outgoing mailbox configured in the AR System Email Mailbox
Configuration form.
c. Enter the appropriate information in the From and Reply To fields.
Note
Make sure you use the same name for the From and Reply To fields.
BMC Remedy Email Engine uses these fields as follows:

From - Indicates the sender; should match the email address of the
corresponding incoming mailbox.
Reply To - Specifies the reply-to address if the recipient replies to the
notification message.
Note
If you set the CC and BCC fields while sending the notification, BMC
Remedy Email Engine displays an error, because the security key is
disabled and more that one recipients are mentioned.
d. In the Organization field, enter a company name, an organization, a keyword, or a

field reference to an organization name.
This name appears in the Organization tag of the email header.
e. In the Header, Content, and Footer fields specify the names of the email templates
to use for the header, content, and footer of the email notification.
6. (Optional) Click the Administrative Information tab and enter Help Text that describes this
notification.
7. Click Save.
Configuring the Request ID link on Approval Central

Application administrators can configure the Request ID link on Approval Central to open one of
the following:

Application request form for the current request

Approval server three-way join form for the current request
A custom form
To configure the Request ID link
1. Log on to an AR System server, and click the Approval Administration Console link on
the home page.
2. On the Administration form, click the Form tab.
3. Perform one of the following to open the AP:Form form.
a. Click Create on the AP:Form, select the approval request form for your application
from the Form Name list.
b. Select a record from the table and click View to modify configurations for an existing
request form.
4. On the Basic tab of the AP:Form form, select one of the following options to configure the
Request ID link on Approval Central:
Application Request Form — To open the application form for the current request
Approval - Application 3-Way Join Form — To open the three-way join form between
the approval server and the application for the current request
Customize — To open a custom form
a. On the AP:Customize-SourceID dialog box, specify the following values:
Display mode in which to open the form
Custom form to be opened
Form view to be displayed
Lookup field or the field mappings (depending on the selected Display mode)
b. Click OK.
For more information, see AP-Customize-SourceID form (see page 1722).
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.
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 (see page 4333).
Configure the approval process to generate a preview at the required time. See Creating a
process (see page 1658).

Design a form that queries the AP:PreviewInfo form. See Adding previews to your approval
application (see page 3021).
Create workflow that uses the Add-PGNA-Values command to gather signatures. See
Defining Parameterized Get Next Approver rules (see page 1688).
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 (see page 1024)

Working with pending approval requests (see page 1025)
Processing More Information requests (see page 1033)
Using alternate approvers (see page 1038)
Performing overrides (see page 1042)
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 (see page 1764).
Working with pending approval requests

The following topics provide information about how to search for specific approval requests, and
provide procedures for managing and responding to approval requests:
Processing an approval request (see page 1025)

Performing a search on Approval Central (see page 1026)
Approving and rejecting requests from Approval Central (see page 1027)
Rejection justification for approval requests (see page 1028)
Working with request details (see page 1029)
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 (see page ) and
Using the Lunch Scheduler sample application (see page 1706).
Processing an approval request

Approvals typically follow this sequence:
1. Someone submits a request that requires your approval.

2. You receive notification of the approval request.
3.
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 (see page 1025), Signature Accumulator rules, (see page 1025) and
Statistical Override rules (see page 1025).
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 (see page 1768).
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
(see page ).
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.
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 (see page 3002).
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
(see page ).
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 (see page 1773).
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
(see page ).
2. In the Pending Approvals table, select the pending request that you want to act upon.
3.
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
(see page 1025).
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 (see page 3003) and Approval forms (see page 1713).
For general information about join forms, see Join forms (see page 2375).
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
(see page ).
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
(see page ).
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 (see page 3020).
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 (see page 1658).

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 (see page 1658).
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 (see page 1033).
To specify next approvers
(see page ).
The relevant request form appears.
3. Click the Show Signatures button.
The appropriate three-way join form is displayed.
Adding multiple approvers

4. In the Next Approver field, enter the names of the next approvers.
You must enter one or more BMC Remedy AR System login IDs. To specify multiple
approvers, separate each name with a semicolon (;) .
5. If you specify multiple approvers, determine the appropriate option for the If Multiple
Approvers field.
One Must Sign — A single signature entry is created for all approvers. Only one of
those approvers needs to take action.
All Must Sign — Separate signature entries are created for all approvers. Each
approver must take action for the request to proceed further.
Note
In an Ad Hoc approval process, if you do not complete the If Multiple

Approvers field, BMC Remedy AR System requires all additional approvers
to sign the request.
6. In the Approval Status field, select Approved.

7. 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
(see page ).
3. In the request form, Click the Show Signatures button.
4. In the Reassign To field on the three-way join form, enter the name of the approver to
whom you want to reassign the request.
You can enter only one person's BMC Remedy AR System login ID.
5. Click Save.
BMC Remedy Approval Server routes the request to the reassigned approver.
Processing More Information requests

If you need more information before approving or rejecting an approval request, you can send a
More Information request, which is an independently-routed BMC Remedy AR System record.
BMC Remedy Approval Server uses the AP:More Information form to manage More Information
requests.
When you create a More Information request, BMC Remedy Approval Server links it to the original
approval request and changes the status of the approval request to More Information. Thus, others
can see that the request is paused until the More Information request is answered.
Your response to the original approval is independent from the More Information request's routing.
In other words, you do not have to wait for the More Information response before approving or
rejecting the approval request. However, if you do approve or reject the original approval request,
BMC Remedy Approval Server immediately closes any related outstanding More Information
requests.
The procedures in the following topics describe the basic steps for requesting more information
and responding to More Information requests:
Requesting more information about approval requests (see page 1034)

Viewing and responding to More Information requests (see page 1035)
Viewing pending More Information requests and responses (see page 1036)
Viewing all the More Information requests you submitted (see page 1037)
The Questions and Comments features that make it easier to work with More Information
Requests. For more information, see AP-Show-Detail form (see page 1783).

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
(see page ).
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
(see page ).
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.
5. Select the request you want to respond to from the results list.
The details area of the form changes to show details of the selected More Information
request.
6. Type your answer in the Response field, and click Save.
The status of the More Information request automatically changes to Completed. The
request no longer appears in the More Information Requests table after the search is
refreshed. BMC Remedy Approval Server routes the response back to the More Information
requester.
Note
By default, the Public group does not have change permission to the Response
field of the AP:More Information form. The BMC Remedy AR System administrator
must set the correct permissions on this field to allow the appropriate groups to
respond to More Information requests.
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
(see page ).
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
(see page ).
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 (see page 1039)
Viewing and modifying alternate approver definitions (see page 1040)
Viewing requests for which you are an alternate approver (see page 1041)
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
(see page ).
2. In the Actions section, click My Alternate Approvers.
The AP:Alternate form opens in New mode.
3.
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
(see page ).
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.
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
(see page ).
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:
Performing an override to a single signature (see page 1042)

Performing a global override (see page 1043)
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. (see page 598)
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).
(see page ).
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).
(see page ).
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.
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 (see page 1044)

Accessing Approval Central (see page 1044)
Creating new approval requests (see page 1044)
Approving approval requests (see page 1046)
Reassigning approval requests (see page 1046)
Requesting more information (see page 1047)
Working with Approval Status and More Information requests (see page 1048)
Responding to and viewing responses to More Information requests (see page 1048)
Checking status of requests (see page 1050)

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
(see page 1635).
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 (see page 1783).
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 (see page ).
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.
5. In the Initial Approvers field, type

Jack Miller; Violet Anderson
Since this is an Ad Hoc process, you must enter at least one approver. To enter multiple
approvers, separate the names with semicolons.
6. Click Save to save the request and begin the approval process.
Approving approval requests

This section demonstrates how an approver responds to a request.
Before you begin

Before approving a request, you must follow the Creating new approval requests (see page )
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 (see page )
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.
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.
Enter the login name and not the first name and last name. In this case, Sue Smith
is a login name.
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 (see page ) procedure.

Follow the Approving approval requests (see page ) 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 (see page ) procedure

Follow the Requesting more information (see page ) 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 (see page 1284).
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.

2.
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 (see page ).
Before trying you check the status of Frank Williams' request, perform the following procedures
(see Approving approval requests (see page )):
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.
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.
Using BMC Remedy Flashboards

The following topics provide general guidelines for working with flashboards you have created or
BMC Remedy Flashboards:
Viewing flashboards (see page 1052)

Sorting flashboards (see page 1052)
Refreshing flashboards (see page 1056)
Displaying tooltips (see page 1056)

Manipulating BMC Remedy Flashboards (see page 1057)

Drilling down to information in a flashboard (see page 1058)
For information about configuring and using the flashboards provided with the BMC Remedy ITSM
implementation, see Configuring flashboards and Using flashboards.
Viewing flashboards
After you add the flashboard to the form and configure the mid tier and BMC Remedy AR System,
you can view your flashboard by opening the form that contains the Data Visualization field with
the flashboard in a web browser.
Note
To view Unicode characters in a flashboards field on the BMC Remedy Mid Tier, you
must have the appropriate language packages installed on the system on which the mid
tier is running.
Sorting flashboards
In versions earlier than 8.1, you could sort BMC Remedy Flashboards based on the labels that
were specified for the charts. In version 8.1, you can sort flashboards based on the values
specified for each data point in ascending or descending order, and display the resulting data.
Note
This feature is not supported in the HTML version of flashboards.
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 (see page 1052)

Types of sorting (see page 1053)
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 (see page ), type the required value in
the Sort Attribute field.
6. Click Save.
To sort flashboards during run time
1. In a web browser, display the flashboard created during design time. For more information,
see Setting up flashboard update intervals.
2. Create a Set Field action for using any of the following parameters and its values defined
during run time:
sortType
sortOrder
sortAttribute
sortIsAttributeEnum
For more information, see Display parameters for charts.
Note
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

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 (see page 3636).
Displaying tooltips
When you hover your mouse over a flashboard, is shows the corresponding values of the
underlying data.
Displaying a tooltip

Tooltips are automatic and available on all types of charts.
Manipulating BMC Remedy Flashboards

If an application includes a flashboard (a graph such as bar chart or pie chart), you can manipulate
the look of the flashboard. You can use the following controls to manipulate the flashboard:
Flashboard controls
Button or Description
field
Opens the Options panel where you can make changes as described in the Changing labels or variables (see page
1058) 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.
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.

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 (see page 241).
Goal Instructions
Configuring servers and applications in the console Navigating the BMC Remedy AR
interface System Administration console
interface (see page 1060)
Setting options in configuration files that are read upon BMC Remedy AR System
startup of BMC Remedy AR System components configuration files (see page 1064)
Understanding processes or utilities and how to set AR System server components

options for BMC Remedy AR System components and and external utilities (see page 1127
external utilities )
Managing passwords, access control, and other Security administration (see page
security matters 1246)
Setting options for user and administration preferences Setting user preferences (see
in the BMC Remedy AR System User Preference form page 1344)
or the BMC Remedy Mid Tier
Managing time periods to define business schedules Defining business schedules

by using BMC Remedy AR System commands using Business Time (see page
1374)
Configuring the server to allow workflow to notify users Enabling alert notifications (see
page 1410)
Automatically specifying the person responsible for Assigning requests with the
handling a request Assignment Engine (see page 1419
)
Allowing search within attached documents and Enabling and disabling full text
increasing search speed in long text fields search (see page 1423)
Configuring the appearance, functionality, and Controlling BMC Remedy AR

processing of your email System through email (see page
1457)
Managing processes and rules for approval requests Setting up the approval process
(see page 1623)
Transferring and managing requests between multiple Setting up DSO to synchronize

servers in various distribution environments data across multiple AR System
Managing the capture of server-related activities, and Capturing server events for
notifying other servers or clients of these changes workflow or API calls (see page
1859)

Goal Instructions
Auditing, archiving, importing, and exporting data, Managing data (see page 1878)
including other BMC Remedy AR System database
matters
Automatically transferring objects and data between Migrating applications and data
AR System servers with workflows between AR System servers (see
page 2052)
Configuring Twitter, RSS feeds, and chat for end users Enabling Social Collaboration in
and receiving BMC Remedy ITSM Suite Twitter alerts BMC Remedy AR System (see
page 2204)
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:
Opening the AR System Administration Console (see page 1060)

AR System Administration Console introduction (see page 1060)
System category (see page 1061)
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.
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.
Opening the AR System Administration Console (see page 1060)

AR System Administration Console introduction (see page 1060)
System category (see page 1061)
Application category (see page 1062)
Admin Preferences category (see page 1063)
User Preferences category (see page 1063)
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 (see page 255).
FTS Configuration — Used to configure FTS. See FTS Configuration form in the AR
System Administration Console (see page 552).
SNMP Configuration — Used to configure the SNMP Agent. See SNMP
Configuration form in the AR System Administration Console (see page 532).
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
(see page 1859).

Add or Remove Licenses — Used to configure license information. See Working

with BMC Remedy AR System licenses (see page 243).
Password Management Configuration — User to force password changes. See
Enforcing a password policy introduction (see page 1310).
Orchestrator Configuration — Used to define the Atrium Orchestrator web service
for BMC Remedy AR System. See Defining BMC Atrium Orchestrator web services
(see page 869).
Web Services Registry — Used to register a web service. See Registering,
modifying, and de-registering web services (see page 3455).
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 (see page 67).
Distributed Mappings — See Distributed mapping (see page 1803).
Distributed Pools — See Distributed pools (see page 1809).
Pending DSO Operations — Managing pending distributed operations (see page
1829).
Distributed Logical Mappings — See Enabling logical mappings (see page 1828).
LDAP — Provides the following links that enable you to configure LDAP. See LDAP plug-ins
in BMC Remedy AR System (see page 789).
ARDBC Configuration — Used to configure the ARDBC plug-in. See Configuring
the ARDBC LDAP plug-in (see page 790).
AREA Configuration — Used to configure the AREA plug-in. See Configuring the
AREA LDAP plug-in (see page 799).
Email — Provides the following links that enable you to configure Email Engine. See
Controlling BMC Remedy AR System through email (see page 1457).
Mailbox Configuration — Used to configure outgoing and incoming mailboxes. See
Configuring outgoing mailboxes (see page 604) and Configuring incoming mailboxes
(see page 627).
Email Templates — Used to create templates for outgoing or incoming email. See
Creating and using email templates (see page 1559).
Email Security — Used to configure outgoing and incoming mailbox security. See
Securing incoming and outgoing email (see page 684).
Email Error Logs — Used to store the logs of errors that have occurred during email
transmissions. See Email error and system status logs (see page 4383).
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 (see
page 1249).

Groups — Used to configure groups. See Creating and managing groups (see page
1255).
Roles — Used to configure roles. See Creating and mapping roles (see page 1266).
License Review — Used to view the current user information. See Viewing user
license information (see page 1336).
Business Time — Used to configure business time. See Defining business schedules using
Business Time (see page 1374).
Reports — Used to configure reports. See Configuring reporting (see page 561).
Report Creator — See Defining BMC Remedy AR System reports (see page 967).
Report Type — See Defining a report type (see page 565).
Currency— Used to configure currency fields. See Currency fields (see page 2580) and
Setting currency types (see page 279).
Currency Codes — See Localizing currency codes (see page 3195).
Currency Label Catalog — See Localizing currency codes (see page 3195).
Currency Localized Labels — See Localizing currency codes (see page 3195).
Currency Ratios — See Currency exchange ratios (see page 2586)
Other— Used to view Message Catalog entries and application state information.
Message Catalog — See Localizing BMC Remedy AR System applications (see
page 3181).
Application States — See Working with deployable application states (see page 2356
) 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 (see page 1344).
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 (see page 1344).
My User Preferences
My Central Files
Search User Preferences
Search User Central Files
Search User Search Preferences

BMC Remedy AR System configuration files

This section contains information about AR System configuration files. Each file is listed by its
UNIX name. If the Microsoft Windows equivalent is different, it appears in parentheses after the
UNIX name.
ar (see page 1064)

ar.cfg or ar.conf (see page 1065)
ardb.cfg or ardb.conf (see page 1122)
armonitor.cfg or armonitor.conf (see page 1126)
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 (see page 1064)

ar environment (see page 1065)
ar scenarios (see page 1065)
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.
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 (see page 1065)

Options (see page 1066)
Environment (see page 1066)
Scenarios (see page 1066)
Synopsis
UNIX — ARSystemServerInstallDir/conf/ar.conf
Windows — ARSystemServerInstallDir\Conf\ar.cfg

Options
For ar.conf options, see:
ar.cfg or ar.conf options A-B (see page 1066)

ar.cfg or ar.conf options C-D (see page 1080)
ar.cfg or ar.conf options E-M (see page 1093)
ar.cfg or ar.conf options N-R (see page 1105)
ar.cfg or ar.conf options S-Z (see page 1114)
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
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.
Note
BMC recommends to use the AR System Configuration Generic UI form to modify the
configuration settings. You should not use the ar.cfg file to modify the configuration
settings available on the AR System Configuration Generic UI form. See Configuration
Settings A-B (see page 1148).
The following tables lists the options available for the ar.cfg (ar.conf) file. Unless otherwise
denoted by the table's footnotes, you can also set these options in the AR System Administration:
This section of the table includes the options for the ar.cfg (ar.conf) file that begin with the letters
A and B.
Note
All options in this file can be manually modified. Entries are case- and space-sensitive, so
be careful when editing this file.
ar.cfg (ar.conf) file options (A-B)
Tips
Press F to view the table in full screen mode. Press Esc to exit full screen mode.
To easily search for a specific parameter in the below table, select the parameter
from the Option list. Alternatively, type the name of the parameter in the Option
text box.
For example, to search for the Admin-Only-Mode parameter, select it from the
Option list, or type the parameter name in the Option text box.
To search for all parameters having a specific text string in the name, type the text
string in the Option text box.
For example, to search for all API parameters, type API in the Option text box.

To search for the parameters which have a specific text string in the description,
type the string in the Description text box.
For example, to search for the parameters which have $\USER$ in the description,
type $\USER$ in the Description text box.
Option Description Maps to
Active-Link-Dir Directory in which active link server run processes are stored. Only commands in the The Security
specified directory can be run. This is a security feature that ensures clients or API area on the
programs use only a safe set of server processes. Advanced tab
of the AR
System
Administration:
Server
Information
form. (See
Setting
performance
and security
options.)
Active-Link-Shell (UNIX only) Parent shell of any active link server process. This parameter causes the The Security
server to start the shell with the specified process as a parameter. This is a security area on the
feature. The specified shell might be a security shell that verifies a path or runs with a Advanced tab
user ID other than the one the server uses. For example, if the server runs as root of the AR
and an administrator specifies a shell that runs as a lower user privilege, an active System
link invokes the shell that runs as a user instead of as root. Because the AR System Administration:
server passes the shell command to the Active-Link-Shell as a single string without Server
any other command-line arguments, the command parameters can often get Information
interpreted incorrectly. The AR System server does not know which custom shell is form. (See
supposed to be used for active link processing, so it does not know how to supply all Setting
of the necessary arguments. In order to avoid this and use the Active-Link-Shell performance
Feature correctly, follow the steps listed below: and security
options.)
1. Determine what your desired shell is, and how to invoke it passing a single
command line. If the desired shell is /bin/csh, the correct way to invoke with a
single command line is
"/bin/csh" "-c" "process command"
2. Write a /bin/sh script that invokes your custom shell in the required manner,
as shown below:
#!/bin/sh
# Usage:
# /path/to/arsystem-csh-helper process-command
# Pass process-command as a command line to /bin/csh.
#
# use "$*" preserve argument as a single string
exec /bin/csh -c "$*"

3.
3. Put the script in a location where the AR System server will be able to call it.
For example, local utilities are often installed in a directory named /usr/local
or /usr/local/bin. Another good location might be the AR System server
installation directory. Be sure to mark the new program executable:
# cp arsystem-csh-helper /usr/local/arsystem-csh-helper
# chmod 755 /usr/local/arsystem-csh-helper
4. In the AR System server configuration, change the Active-Link-Shell to be the

new program /usr/local/arsystem-csh-helper
Admin-Only-Mode Flag indicating whether only administrators and subadministrators can access the The
server. Values are Administrator-
Only Mode
T — Admin-only mode is on. field on the
F — (Default) Admin-only mode is off. Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Allow-Backquote-In- Option that enables the server to run a process with a backquote in the process
Process-String 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 The Allow
(users not registered with BMC Remedy AR System in a User form). Values are Guest Users
field on the
T — (Default) Allow guest users. Unregistered users have no permissions but Configuration
can perform some basic operations. For example, they can submit requests to tab of the AR
forms to which the Public group has access and whose fields allow any user to System
submit values. Administration:
F — Do not allow guest users. Unregistered users have no access to the Server
system. Information
form. (See
Setting
administrative
options.)
Allow-Unqual- Flag indicating whether unqualified searches can be performed on the BMC Remedy The Allow
Queries AR System server. Unqualified searches are ARGetListEntry or Unqualified
ARGetListEntryWithFields calls in which the qualifier parameter is NULL or has an Searches field
operation value of 0 (AR_COND_OP_NONE ). Such searches can cause on the
performance problems because they return all requests for a form. This is especially Configuration
problematic for large forms. Values are tab of the AR
System
T — (Default) Allow unqualified searches. Administration:
F — Do not allow unqualified searches. Server
Information

form. (See
Setting
administrative
options.)
Alternate-Approval- Flag indicating how applications such as Approval Server or Reconciliation Engine
Reg 2 listen for the BMC Remedy AR System server's signal. Values are
T — (default) Listen for the application dispatcher to signal.

If your application relies on the application dispatcher, set this option to T. To
verify that arsvcdsp is configured to start with the BMC Remedy AR System
server, check the armonitor.cfg (armonitor.conf ) file.
F — Listen for the server's signal directly.
API-Log-File Full path name of the file to use if API logging is on (See Debug-mode). The API Log
field on the
Log Files tab
of the AR
System
Administration:
Server
Information
form. (See
Setting log
files options.)
API-SQL-Stats- A bit mask value indicating options selected.

Control
API-SQL-Stats-Max- Maximum number of longest API and SQL operations saved in memory. The default
Saved-Long- is 20 of each type. The highest value allowed is 100.
Operations
API-SQL-Stats-Flush- Time, in minutes, between flushing the longest operations from memory to the forms.
To-DB-Interval A value of 0 (the default) means that there is no automatic flushing.
API-SQL-Stats- Minimum elapsed time an operation must have to qualify for recording. The default is
Minimum-Elapsed- 5000 milliseconds (or 5 seconds).
Time
Approval-Defn- Interval (in seconds) at which Approval Server checks for changed or updated data in
Check-Interval 2 the data definition forms.
Approval-Debug- Type that specifies the logging level for the approval logs of the Approval server. The Logging
Type Settings area
Values are
on the Basic
tab of the AP:
NORMAL— Use this value to set the minimum logging level for approval logs.
Admin-
Note: When Approval-Debug-Type is set to NORMAL, only severe issues are
ServerSettings
written to the logs.
form. (See
ALL— Use this value to set the maximum logging level for the approval logs.
Configuring
Default value: Normal server settings
for BMC
Remedy
Approval

Server logging
and loopback
calls (see page
4333).)
Approval-Due-Soon1 Specifies the Due-Soon Interval in hours or days for the approval requests that are
displayed when an approver logs in to Approval Central.
Approval-Log-File 2 Full path of the Approval Server log file.
Approval-Notify 2 Flag indicating whether approval notifications are configured from the Server Settings
dialog box. An Approval-Notify entry exists for each ID. 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 at which the Approval Server polls the AR System server for pending work.
Interval This setting is intended as a backup method, not the primary contact method. Under
normal circumstances, the AR System server or the Application Dispatcher
(depending on the configuration) contacts the Approval Server when work is pending.
When this option is specified, the Approval Server polls the AR System server only if
it does not receive a signal from the AR System server in the specified time.
Specify the interval in seconds. Minimum is 30 seconds. Maximum is 3600 seconds

(one hour).
If the interval value is not specified, the default value (1800 seconds or 30 minutes) is
considered.
Approval-Recent- Specifies the Recent History Interval in hours or days for the approval requests that
History1 are displayed in the My Approval History section of Approval Central for an
approver.
Approval-RPC-Socket RPC Program Number that Approval Server uses when contacting BMC Remedy AR
2 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- Base distinguished name (DN) to use instead of the root DN as the starting point for The Base DN
DN discovering vendor tables when you design vendor forms. For example: ARBDC- For Discovery
LDAP-Base-DN: CN=Users, DC=ldapesslab, DC=com field on the
ARDBC LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Cache- Size limit (in bytes) for the cache. For no size limit, set this to 0. The default is 32768 The Maximum
MaxSize bytes. Size field in
the ARDBC
Plugin Cache
box on the
ARDBC LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Cache- Time limit (in seconds) that data remains cached. For no time limit, set this to 0. The The Time To
TTL default is 60 seconds. Live field in
the ARDBC
Plugin Cache
box on the
ARDBC LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Cert- Directory name of the certificate database. The cert8.db or cert7.db and key3.db The
DB certificate database files are in this directory. If the directory is not specified, the Certificate
LDAP plug-in looks in the BMC Remedy AR System installation directory for these Database field
files. The path in this option is used only when ARDBC-LDAP-UsingSSL is set toT. on the ARDBC
LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Cert- Not yet implemented.

Name 2
ARDBC-LDAP-Chase- Flag that enables automatic referral chasing by LDAP clients. Values are
Referrals 2
T — Referrals are chased.
F — (Default) Referrals are not chased.
This option is for Microsoft Active Directories only.

ARDBC-LDAP- Number of seconds that the plug-in waits for a response from the directory service
Connect-Timeout 2 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- Number of seconds that the plug-in retains the base distinguished name (DN) used to
Timeout 2 access an LDAP ARDBC vendor form after the user becomes inactive. The default is
3600 seconds.
ARDBC-LDAP-Drop- Obsolete in version 7.0.00 and later.

Large-Values 2
ARDBC-LDAP- Host name of the system on which the directory service runs. If the host name is not The Host
Hostname specified, the ARDBC LDAP plug-in uses localhost as the host name. For example: Name field on
ARDBC-LDAP-Hostname: server1.eng.remedy.com the ARDBC
LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Key- Not yet implemented.

DB 2
ARDBC-LDAP-Key- Not yet implemented.

Password 2
ARDBC-LDAP-Page- Page size in the pagedResultsControl of the ARDBC LDAP plug-in search request.
Size 2 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 Port number on which the directory service listens for clients. The Port
Number field
on the ARDBC
LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Time- Format of LDAP date and time data. Values are

Format 2
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- Flag that enables caching of search requests. Values are T and F. After caching is
Cache 2 enabled, search requests issued via the ARDBC plug-in are cached. Subsequent
matching search requests are satisfied from the cache.

ARDBC-LDAP-User- Distinguished name (DN) of the user account that the ARDBC LDAP plug-in uses to The Bind User
DN search and modify the contents of the directory service. For example: ARDBC-LDAP- field on the
User-DN: server1\admin ARDBC LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
ARDBC-LDAP- Flag indicating whether to establish a secure socket layer (SSL) connection to the The Using
UsingSSL directory service. Values are T and F. If you use LDAP over SSL, you must also Secure
specify the file name of the certificate database used to establish the connection. Socket Layer
field on the
ARDBC LDAP
Configuration
form. (See
Configuring
the ARDBC
LDAP plug-in.)
AREA-LDAP-Bind- Password of the user account that the AREA LDAP plug-in uses to find the user The Bind
Password object when using the User Search filter. If the distinguished name (DN) is not Password
specified, the AREA LDAP plug-in uses an anonymous login to find the user object. If field on the
the target directory service does not allow anonymous access, you must specify a AREA LDAP
DN and password; otherwise, the plug-in cannot determine the DN of the user. Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-Bind- Distinguished name (DN) of the user account that the AREA LDAP plug-in uses to The Bind User
User find the user object when using the User Search filter. If the DN is not specified, the field on the
AREA LDAP plug-in uses an anonymous login to find the user object. If the target AREA LDAP
directory service does not allow anonymous access, you must specify a DN and Configuration
password; otherwise, the plug-in cannot determine the DN of the user. For example: form. (See
AREA-LDAP-Bind-User: ldapesslab\admin Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-Cert-DB Directory name of the certificate database. The cert8.db or cert7.db and key3.db The
certificate database files are in this directory. If the directory is not specified, the Certificate
LDAP plug-in looks in the BMC Remedy AR System installation directory for these Database field
files. This path is used only when ARDBC-LDAP-UsingSSL is set to T. in the
Directory
Service
Information
area on the
AREA LDAP
Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-Chase- Flag that specifies whether referral chasing is performed by the AD server or the The Chase
Referral 2 AREA LDAP plug-in. Values are Referral field
in the

T — Referral chasing is performed by the AD server. Directory

F — (Default) Referral chasing is performed by the AREA LDAP plug-in (via Service
the third-party LDAP library). Information
area on the
This option is for Microsoft Active Directories only. AREA LDAP
Configuration
Note: To force referral chasing logic to be disabled, you must also specify the AREA-
form. (See
LDAP-Disable-Referral option. (See ar.cfg or ar.conf options A-B.)
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP- Number of seconds that the plug-in waits to establish a connection with the directory The Failover
Connect-Timeout service. The minimum value is 0, in which case the connection must be immediate. Timeout field
The maximum value is the External-Authentication-RPC-Timeout setting. If a value in the
is not specified, this option is set to the value of the External-Authentication-RPC- Directory
Timeout option (by default, 40 seconds). Service
Information
area on the
AREA LDAP
Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-Disable- Flag that disables all referral processes by the AREALDAP plug-in. Values are
Referral 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- Value that the AREA LDAP plug-in uses if the AREA-LDAP-Email parameter is not
Default 2 specified or has no value for the user.
AREA-LDAP-Group- Base of the LDAP directory to search groups from. To determine the option's values The Group
Base at runtime, use these keywords: Base field in
the User and
Note: The backslash (\) is required.
Group
Information
$\USER$ — User's login name.
area on the
$\DN$ — User's distinguished name. This applies only to the Group Base
AREA LDAP
Name and Group Search Filter. It does not apply to the User Base name and
Configuration
User Search filter.
form. (See
$\AUTHSTRING$ — Value that users enter into the Authentication String field
Configuring
when they log in.
the AREA
$\NETWORKADDR$ — IP address of the AR System client accessing the AR
LDAP plug-in.)
System server.

AREA-LDAP-Group- Default groups to which the user belongs if no group information is available from the
Default 2 directory service. If the user belongs to multiple groups, use a semicolon to separate
them.
AREA-LDAP-Group- LDAP search filter used to locate the groups to which the user belongs. To determine The Group
Filter the option's values at runtime, use these keywords: Search Filter
field in the
User and
Group
Information
$\DN$--- User's distinguished name. This only applies to the Group Base
area on the
Name and Group Search Filter. It does not apply to the User Base Name and
AREA LDAP
User Search Filter.
Configuration
form. (See
when they log in.
Configuring
the AREA
System server.
LDAP plug-in.)
AREA-LDAP- Host name of the system on which the directory service runs. If no value is specified, The Host
Hostname the AREA LDAP plug-in uses localhost as the host name. Name field in
the Directory
Service
Information
area on the
AREA LDAP
Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-Lic 2 Name of the attribute that identifies the type of write license issued. This attribute
corresponds to the License Type field in the BMC Remedy AR System User form. If
the attribute is not specified, the specified default or a system default is applied.
AREA-LDAP-Lic- Value that the AREA LDAP plug-in uses if the AREA-LDAP-Lic attribute is not
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- Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicApp attribute is not
AREA-LDAP-LicMask Attribute that specifies how to mask the license information returned from the AREA The License
LDAP plug-in. Values are Mask field in
the Defaults
0--No licenses returned from the AREA LDAP plug-in are used. and Mapping
1--Write license from the plug-in is used. Attributes to
4--Reserved license from the plug-in is used. User
5--Reserved license and Write license from the plug-in are used. Information
8--Application license from the plug-in is used. area on the
9--Application and Write licenses from the plug-in are used. AREA LDAP
12--Application and Reserved licenses from the plug-in are used. Configuration
13--All licenses from the plug-in are used.

form. (See
If the license is not used from the plug-in, the license information in the user's User Configuring
entry is used. the AREA
LDAP plug-in.)
AREA-LDAP- Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicMask attribute is not
LicMask-Default 2 specified or has no value for the user.
AREA-LDAP-LicRes1 Name of the attribute that specifies the type of reserved license issued. If the attribute
2 is not specified, the specified default or a system default is applied.
AREA-LDAP-LicRes1- Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicRes1 attribute is not
AREA-LDAP-Notify- Name of the attribute that specifies the default notification mechanism for the user.
Meth 2 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- Value that the AREA LDAP plug-in uses if the AREA-LDAP-Notify-Meth attribute is
Meth-Default 2 not specified or has no value for the user.
AREA-LDAP-Port Port number on which the directory service listens for clients. The Port
Number field
in the
Directory
Service
Information
area on the
AREA LDAP
Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-SSL- Flag indicating how the secure connection is established. By default, AREA-LDAP-
AUTH-OPTION 2 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- Flag indicating whether to retrieve group information from the LDAP server. If this The Group
Groups parameter is not set, group information from the AR System Group form is used. Membership
field in the
User and
Group
Information
area on the
AREA LDAP
Configuration
form. (See
Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-User- User base in the LDAP directory to search for the user. To determine the option's
Base values at runtime, use these keywords:

Note: The backslash (\) is required. The User Base

field in the
$\USER$ — User's login name. User and
$\DN$ — User's distinguished name. This only applies to the Group Base Group
Name and Group Search Filter. It does not apply to the User Base Name and Information
User Search Filter. area on the
$\AUTHSTRING$ — Value that users enter into the Authentication String field AREA LDAP
when they log in. Configuration
$\NETWORKADDR$ — IP address of the AR System client accessing the AR form. (See
System server. Configuring
the AREA
LDAP plug-in.)
AREA-LDAP-User- LDAP search filter used to locate the user in the directory from the base that the The User
Filter AREA-LDAP-User-Base option specifies. To determine the option's values at Search Filter
runtime, use these keywords: field in the
User and
Group
Information
area on the
$\DN$ — User's distinguished name. This only applies to the Group Base
AREA LDAP
Name and Group Search Filter. It does not apply to the User Base Name and
Configuration
User Search Filter.
form. (See
Configuring
when they log in.
the AREA
LDAP plug-in.)
System server.
AREA-LDAP-UseSSL Flag indicating whether to establish a secure socket layer (SSL) connection to the The Use
directory service. Values are T and F. If you use LDAP over SSL, you must also Secure
specify the file name of the certificate database used to establish the connection. 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 of errors that trigger a dump of the current stack in the arerror.log file. Separate
List 2 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- Java command options for a virtual machine (VM). The options are documented in
Options 2 the online AR System Java API documentation.
ASJ-Thread-Count Specifies the total number of worker threads that process various approval requests.
The minimum value is 1. The maximum value is 4. The default value is 4.

Note: If the specified value is not within the maximum and minimum value, the
default value is applied. If a value is not specified, this option is set to the default
value.
Attachment- Parameter which allows you to override the Attachment Security functionality
Exception-List implemented in the AR System Administration: Server Information form. To override
the attachment restrictions, you can specify the Form name with Field ID and upload
attachments only for that field ID.
Note: Field ID is the numeric value of the field that contains an attachment on the
form. You can get the value for a Field ID from the Developer Studio.
For example,
If attachments of the type PDF have been disabled in the AR System Administration:
Server Information > Attachment Security > Attachment criteria, it should still be
possible for PDF based reports to be scheduled and published. To solve such a
problem, in the AR System Administration: Server Information > Attachment Security
> Attachment exception list, enter form name and field ID combination, such as AR
System Publish Report(90104), to override the attachment security setting. The PDF
attachments will now be allowed for field ID 90104 on the AR System Publish Report
form, even if PDF attachments are disallowed globally. Similar entry can be made for
other forms like the AR System Resource Definitions form, and for the field ID 41103
as AR System Resource Definitions(41103).
For multiple form and field ID entries, enter a comma separated list like AR System
Publish Report (90104), AR System Resource Definitions(41103) in the Attachment
exception list field.
For more information, see Setting security restrictions on file uploads
Attachment-System- Defines the attachments that cannot be attached in an entry operation.

Exception-List1
Authentication- Mode that enables the administrator to use more than one type of authentication on
Chaining-Mode 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.
Auth-Token- Defines the encryption key to be used for authentication token. Usually not to be
Signature-Salt1 changed unless invalid tokens are being received.
ARSYS.ARF. Name of a plugin used by the BMC Remedy AR System server to confirm the user
ATSSOCONFIRMPWD password information from the BMC Atrium Single Sign-On server.
ar.cfg or ar.conf options C-D
Settings C-D (see page 1168).
This table contains the options for the ar.cfg (ar.conf) file that begin with the letters C and D.
ar.cfg (ar.conf) file options (C-D)
Tips
text box. For example, to search for the Cache-Mode parameter, select it from the
string in the Option text box. For example, to search for all Cache parameters,
type Cache in the Option text box.
For example, to search for the parameters which have ARCreateEntry() in the
description, type ARCreateEntry() in the Description text box.

Cache- The way that the server caches form display properties. The form display property is the
Display- background image of the form view and the display property of each form field. Valid values:
Properties 2
T — (Default) Cache all form-display properties.
F — Cache only server-display properties. (This can negatively impact the
performance of the server if a form is changed, but it reduces the amount of memory
used in the server cache.)
Cache-Mode The valid value for Cache-Mode is, The

Development
0 — (Default)
Cache Mode
Note: You should always set the value for Cache-Mode to 0. field on the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Note: You
should not
change the
default value
for the
Development
Cache Mode
checkbox.
Cancel-Query- Flag indicating whether the cancel query functionality in a browser is enabled. Valid values:
Option 2
0 — Inactive
1 — (Default) Active
Changed-By- Flag indicating whether the system checks whether another user changed an entry after you
Another- retrieved the entry. If you try to save modifications to an entry, you receive a warning and
Check must confirm the save. Valid values:
T — (Default) Perform the check and issue a warning.

F — Do not perform the check.
Client- Maximum time (in seconds) to hold a transaction before a timeout occurs. The default is 60 The
Managed- seconds, and there is no maximum. If a timeout occurs, the server automatically rolls the Transaction
Transaction- transaction back, and the client receives an error on the next operation that uses the Timeout
Timeout transaction handle. (seconds) field
in the
Transaction
Control area
on the
Advanced tab
of the AR
System

Administration:
Server
Information
form. (See
Setting
performance
and security
options.)
Clustered- Flag indicating whether indexes for the database are clustered. Valid values:
Index
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- Specifies the time interval in milliseconds after which the CMDB refreshes its cache in the
Refresh- background. Default value: 900000
Initial-Delay1 Note: If the value defined for this parameter is less than 60000 milliseconds (60 seconds),
the default value is taken.
CMDB-Cache- Frequency, in seconds, at which the BMC Atrium CMDB cache is refreshed. The default
Refresh- value is 300 seconds (5 minutes). For more information about the cache refresh interval, see
Interval 2 Setting the cache refresh interval.
CMDB- Specifies the time interval in milliseconds after which the data will be treated as orphaned
ChunkedItem- and the memory can be reclaimed by server.
Allowed- Default value: 3600000 Note: The value for this parameter should be greater than 60000
Period-In- milliseconds (60 seconds), if it is not then the default value is taken.
Cache1
CMDB- Specifies the time interval in milliseconds to start checking for the orphan data after CMDB
ChunkedItem- server has started. Default value: 900000
Cleanup- Note: The value for this parameter should be greater than 60000 milliseconds (60 seconds),
Initial-Delay1 if it is not then the default value is taken.
CMDB- Specifies the time interval in milliseconds at which the CMDB server should perform the
ChunkedItem- orphan data checks. To disable this parameter set a value to minus -. For example, -1.
Cleanup- Default value: 300000
Interval1 Note: The value for this parameter should be greater than 60000 milliseconds (60 seconds),
if it is not then the default value is taken.
CMDB- Sets the CI viewer graph limit.

CIViewer-
Graph-Limit1
CMDB- Sets the limit for number of levels of recursion for CMDB graph query.
GQRecursion-
Limit1
CMDB-Hard- Specifies that all the CIs that are Marked As Delete (MAD) are to be deleted.
Delete-Only-If-
Marked-For-
Delete1
Specifies the default weight attached to impact relationship. This value is used in Atrium
Impact Simulation.

CMDB-
Impact-
Weight-
Default1
CMDB-Log- Specifies the path on the server where the log file is saved.
File-Location1
CMDB-Log- Specifies the name of the CMDB log file.

File-Name1
CMDB-Max- Specifies the maximum number of results that are returned per query. If this value is 0 it
Results-Per- means that the maximum results per query are unlimited.
Query1
CMDB- Specifies the number of backup CMDB log files to be maintained.

Number-Of- Default value: 10
Backup-Files1
Configure- Indicates whether log4j package should be configured from the external properties file log4j.
Log4j1 properties.
Configuration- Defines the name of the component. AR System server uses this option to identify the active
Name1 component in the database.
Create-Entry- Number of times to retry the ARCreateEntry() function during deadlock situations. Value is
DeadLock- an integer.
Retries 2
Default value - 3 (3 retries)
Create-Entry- Delay, in seconds, between each retry of a deadlocked ARCreateEntry() function. Value is
DeadLock- an integer.
Retries-Delay
2 Default value - 0 (Retries happen immediately, without a delay)
Crossref- Flag indicating how the system responds when a user's logon name is not assigned a
Blank- password in the User form. Valid values:
Password
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- Number of minutes between each refresh of currency conversion ratios on the client.
Ratio-Client-
Refresh-
Interval 2
Db-Case- Flag indicating whether to perform case-insensitive queries on Run If qualifications for active
Insensitive 1 links, filters, and escalations. (For Oracle databases, ensure that this option matches the
behavior of your Oracle database so that all queries are consistent.) Valid values:

T — Performs case-insensitive search. Setting this parameter in the ar.cfg (ar.conf)

file causes special session parameters (NLS_SORT and NLS_COMP) to be set to
support case-insensitive searches and invalidate existing database indexes. By
default, the AR System server creates regular indexes when you add an index to a
form. To support case-insensitive searches on Oracle databases, functional indexes
are required instead of regular indexes. To change the AR System server's default
behavior for index creation, set the Db-Functional-Index parameter to T. For more
information, see Db-Functional-Index.
F (the default) — Performs case-sensitive queries.
To learn how to enable case-insensitive search for fixed-length text fields in BMC Remedy
AR System version 8.1 on Oracle, see the BMC Knowledge Base article KA406947.
Db-Character- Option that initializes an internal variable that the server uses for various purposes, such as
Set 2 informing the ARGetServerInfofunction's AR_SERVER_INFO_DB_CHAR_SET server
option request or adjusting the database short column size so that the number of characters
in a datum does not exceed the number of bytes in the database field. Valid values:
Unicode (UTF-16) — UTF-16 UCS-2

Unicode (UTF-8) — UTF-8
Note: The installer sets this option's value.
Db- Number of times the BMC Remedy AR System server tries to reestablish a lost connection to
Connection- the database. The default is 100. The server retries the connection once every 15 seconds
Retries 2 up to the specified number of times. For example, when this option is set to 100, the server
retries the connection once every 15 seconds for a duration of 25 minutes.
Db-
Functional-
Option to change the AR System server's default behavior for index creation. To change the
Index 1
AR System server's default behavior for index creation, set the Db-Functional-Index
parameter to T. Then, when a new index is added to a form, the AR System server creates a
functional index for the form. This parameter helps to avoid performance degradation that
can result from not using database indexes. The Db-Functional-Index parameter is ignored
if Db-Case-Insensitive is set to F or if it is absent from the ar.cfg file. The Db-Case-
Insensitive and Db-Functional-Index parameters handle new indexes. In the database
(outside of the AR System server), you must manually convert any existing indexes to
functional indexes. BMC provides an unsupportedOracleFunctionalIndexHelper.bat utility
to manage these existing indexes and to convert them from regular to functional indexes.
You can find this unsupported utility in the ARServerInstallDirectory\Arserver\api\lib
folder. Due to known issue with Oracle, set cursor sharing to EXACT so that the query
optimizer can use functional indexes for LIKE queries. For help, see your database
administrator.
Note: While running the OracleFunctionalIndexHelper.bat utility for existing forms, you
might see the following error: Error message ERROR (552): The SQL database operation
failed.; ORA-00942: table or view does not exist. This occurs because indexes are not
applicable on vendor, view, display-only, and join forms.
For optimal performance when using database indexes for case-insensitive searches on
Oracle, ensure that:
The Oracle client is at least version 11.2.

The database administrator sets cursor sharing to EXACT for the functional indexes
that Oracle Optimizer will use (otherwise, performance can be severely degraded due
to full table scans).

Note: Depending on the volume of data, creating functional indexes may take a long time.
Db-Host- Defines the name of the Database Server.

Name1
Db-Max- Maximum size (in bytes) of compressed attachments that the AR System server can retrieve
Attach-Size2 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- (Oracle, Microsoft SQL Server, and Sybase) Maximum size for long character text data in
Size 2 databases. For Oracle databases, this value is also used for memory allocation during the
processing of long text data; therefore, use it conservatively. The default for an Oracle
database is 4,194,308 bytes. For SQL Server and Sybase, the default is 2,147,483,647
bytes. The maximum value for either database is 2,147,483,647 bytes.
Db-name 1 For Oracle, the name of the tablespace that the AR System server uses. For all other
supported databases, the name of the underlying SQL database. The default value is
ARSystem.
Db-password (DB2, Microsoft SQL Server, Oracle, and Sybase) Database password associated with the
ARSystem database and table space. The password can be modified by using the
ARSetServerInfo function and is stored in encrypted form. If you change the password
manually, specify this option by using clear text, and change the password by using the AR
System Administration: Server Information form to encrypt it.
Db-Server- Defines the database port number.

Port1
Db-Type1 Defines the type of database the AR System server is connecting to.
Valid values:
sqlserver
oracle
Db-user 1 (Microsoft SQL Server, Oracle, and Sybase) User name that AR System uses to access the
underlying database. The default is ARAdmin.
DB-Database- DB database alias name for the AR System database.

Alias
DB-Server- DB database server name.

Name
Dbhome- (SQL databases on UNIX only) Full path name of the home directory for the underlying
directory 1 database.
Debug- Name of the group to which a user must belong to use logging options such as API,
GroupId 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 theEscalation-Log-File option.
Bit 5 (value = 16 ) — Turns on API logging in the default arapi.log file. To specify a
different file, use the API-Log-Fileoption.
Bit 6 (value = 32 ) — Turns on thread logging in the default arthread.log file. To
specify a different file, use the Thread-Log-File option.
Bit 7 (value = 64 ) — Turns on alert logging in the default aralert.log file. To specify a
different file, use the Alert-Log-File option.
Bit 8 (value = 128 ) — Turns on arforkd logging in the default arforkd.log file. To
specify a different file, use the arfork-Log-File option.
Bit 9 (value = 256 ) — Turns on server group logging in the default arsrvgrp.log file.
To specify a different file, use theServer-Group-Log-File option.
Bit 10 (value = 512 ) — Turns on logging for full text indexing in the default arftindx.
log file. To specify a different file, use the Full-Text-Indexer-Log-File option.
Bit 16 (value = 32768 ) — Turns on DSO server logging in the default ardist.log file.
To specify a different file, use theDistrib-Log-File option.
Bit 17 (value = 65536 ) — Turns on Approval Server logging. To specify the location
for the arapprov.log file, use the Approval Menu > Server Settings > AP: Admin-
Server Settings form.
Bit 18 (value = 131072 ) — Turns on plug-in logging in the default arplugin.log file.
To specify a different file, use thePlugin-Log-File option.
Default- Default allowable currency types for currency fields in clients.

Allowable-
Currencies
Default- Default functional currency types for currency fields in clients.

Functional-
Currencies
Default- Specifies port for JMS (Java Messaging Service) used by Java server for asynchronous
messaging- communication within server or server group. Default value is 61617.
port
Default-Order- Flag indicating whether to apply the default sort order to search results. Valid values:
By 2
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- URL to the directory path for the default web server pointing to the BMC Remedy AR System The Default
Path server. Web Path field
on the
Advanced tab

of the AR
System
Administration:
Server
Information
form. (See
Setting
performance
and security
options.)
Delay- Number of seconds before the latest cache is made available to all threads. Valid values: 0 The Recache
Recache-Time to 3600 seconds. If this option is set to 0, every API call gets the latest cache (that is, the Delay field on
cache is copied for every administrator call). Setting the option to 0 causes slower the
performance for cache operations. Configuration
tab of the AR
The default value is 5 seconds. The recommended value is 300 (5 minutes).
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable- Flag indicating whether administrative operations are allowed on the server. Valid values: The Disable
Admin-Ops Admin
F — (Default) Disabled Operations
T — Enabled field on the
If the Server Groups check box is selected, this option is ignored. Server groups can Configuration
be configured in the BMC Remedy AR System Server Group Operation Ranking form tab of the AR
to make sure that only one server performs the operation. See Configuring server System
groups. Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable-Alerts Flag indicating whether alerts are sent when alert events are created. Valid values: The Disable
Alerts field on
T — No threads are started in the alert queue, and no alerts are sent. the
F — (Default) Alerts are enabled. Configuration
tab of the AR
Changes to this setting do not take effect until the server is restarted. System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable- Switch that disables (T ) or enables (F ) the archive when the server starts.
Archive

The Disable
Archive field
on the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable- Flag indicating whether automatic signals triggered by changes to the following data on a The Disable
ARSignals server group's administrative server are disabled: ARSignals
field on the
Archive definitions Configuration
Escalation definitions tab of the AR
Group information from the database System
Administration:
The signals can be generated by arsignald or the database. Signals triggered by Server
changes to user, licensing, and computed group information are not disabled. Valid Information
values: form. (See
T — The specified signals are disabled. Setting
F — (Default) Automatic signaling remains in effect for all object definition changes. administrative
options.)
To send the disabled signals manually, use the arsignal program (See arsignal.exe or
arsignal. See Configuring the server group signaling option.)
Disable-Audit- Flag indicating whether to audit all records (T ), or to audit only those records whose field The Disable
Only- values have changed (F, the default). Audit Only
Changed- Changed
Fields Fields field on
the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable- Option that restricts time-consuming operations (such as reporting) during busy times,
Client- improving overall performance. The syntax is
Operation 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. For more
information on the list of Client types, see List of Client Type ID (see page 2794).
Disable- Flag indicating whether escalations are allowed on the server. Valid values: T and F The Disable
Escalations (default). If the Server Group Member check box is selected, this option is ignored. Server Escalations
groups can be configured in the BMC Remedy AR System Server Group Operation Ranking field on the
form to make sure that only one server performs the operation. (See Configuring server Configuration
groups.) tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable-Non- Flag indicating whether Unicode servers can refuse requests from non-Unicode clients (for The Disable
Unicode- example, not Mid Tier 7.0.00). This option does not affect non-Unicode servers. Valid values: Escalations
Clients field on the
T — Unicode servers refuse requests from non-Unicode clients. Configuration
F — (Default) Unicode and non-Unicode clients can contact Unicode servers. tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)
Disable-User- Flag that prevents unauthorized users from using User Cache commands. Valid values:
Cache-
Utilities T — The *arreload* and arcache utilities are disabled for the AR System server.
F — (Default) Cache utilities are enabled.
Dispatch-Log- Flag that indicates whether the dispatcher logging is enabled. Valid values:
File

T — The dispatcher logging is enabled. When you enable the dispatcher logging,
specify the log filename that you want to use.
F — (Default) The dispatcher logging is disabled.
Display- Flag indicating whether to display a message when user authentication fails. Valid values:
General-Auth-
Message2 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- Full path name of the file to use if DSO server logging is on (See Debug-mode).
File
Distributed- The BMC Remedy AR System server to use for the DSO server. By default, the DSO server
RPC-Socket runs in queues like any other user.
Obsolete. (See Assigning an RPC program number to DSO.)
Domain-Name New domain name portion of the fully qualified server name. By default, a server determines
2 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- Number of seconds between occurrences of these operations:

Check-
Interval 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- DSO server retry behavior after an error:

Retry-Option
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 to use for the From (source) server in distributed mappings. This setting enables you
Name 2 to use an alias for the From server in distributed operations.
DSO-Local- RPC program number that DSO uses. This setting is optional. The DSO
RPC-Socket Local RPC
Program
Number field
in the DSO

Server area on
the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting server
passwords,
RPC options,
and plug-in
timeouts.)
DSO-Log- Level of logging for all DSO logs (ardist.log, ardist.log.default, ardist. poolName.log, and
Level ardist.log. poolName ):
0 — Logs only errors. Includes contextual information.

1 — Logs errors and warnings. Includes contextual information.
2 — Logs errors, warnings, and other information to provide a step-by-step record of
DSO activities.
(See BMC Remedy Distributed Server Option logging and Setting log files options.)
DSO-Log- Number of indexed backup files saved for each DSO Java log file. If you do not specify a
Max-Backup- value for this option, 5 indexed backups are saved for each DSO Java log file.
Index 2
DSO-Main- Interval at which the DSO server queries the distributed pending queue for pending
Thread- distributed items. Enter any integer from 0(no polling) to 3600 seconds (1 hour).
Polling-
Interval
DSO-Mark- Flag indicating whether to set the status of items in the DSO distributed pending queue to
Pending- Retry after an attempt to perform the associated operation fails. (Failure must be due to a
Retry-Flag 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- Maximum number of records in the Distributed Pending form that DSO reads in a single
Pending- database query. Minimum value is 1. Maximum value is unlimited. If no value is specified, the
Records-Per- default is 1000.
Query
DSO-Merge- The way the DSO server behaves when it finds a duplicate request ID on the target server.
DupID- Valid values:
Overwrite 2
T — Updates mapped fields and sets unmapped fields to NULL.

F — (Default) Updates only the mapped fields on the target request.
DSO- Mode that disables the DSO server installed on the same host as the AR System server. Use
Placeholder- this when setting up a DSO server outside a firewall to support an AR System server running
Mode behind a firewall.
DSO-Polling- Interval (in seconds) at which the DSO server checks the distributed pending queue for
Interval 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- The AR System server for a DSO server to support when that AR System server is different
Server 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- Flag indicating whether to log AR System server error 302 (entry does not exist in database)
No-Such- in the*arerror.log* file when performing distributed delete operations. Valid values:
Entry-For-
Delete 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- Information for the target BMC Remedy AR System server. Use this format:DSO-Target- The Target
Connection Connection:serverName:RPCNumber portNumber connection
settings tables
field in the
DSO Server
area on the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting server
passwords,
RPC options,
and plug-in
timeouts.)
DSO-Target- Password used to access the target BMC Remedy AR System server through the DSO
Password server. Use this format:DSO-Target-Password: serverName:encryptedPassword
DSO-Timeout- Timeout (in seconds) that the DSO server applies during communication with the AR System
Normal server. Enter an integer between60 (1 minute) and 21600 (6 hours). If no value is specified,
the system uses the default timeout (120 seconds).
DSO-User- Password for the local DSO server user.

Password

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.
ar.cfg or ar.conf options E-M
Note
Settings E-M (see page 1201).
E through M.
ar.cfg (ar.conf) file options (E-M)
Tips
text box.
For example, to search for the Escalation-Log-File parameter, select it from the
For example, to search for all Email parameters, type Email in the Option text
box.
For example, to search for the parameters which have Security in the description,
type Security in the Description text box.
Email-Notify- Sender name to use for filter-generated email notifications in which no subject is
From 2 specified. The value is limited to 29 characters.

Email-Timeout Obsolete in version 5.1.0 and later.

2
Enable- Flag indicating whether log files display complete lines into log files or not. Values
Unlimited-Log- are:
Line-Length
T — AR System server logs complete lines into log files without truncation.
F — (Default) AR System server logs only 4093 characters per line, including
the header information.
For more information, see BMC Knowledge Base article KA308638.
Encrypt-Data- Integer indicating the encryption algorithm of the data key. Use the following values.
Encryption-
Standard Security
Algorithm
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- Integer indicating the encryption algorithm of the public key. Values are
Public-Key-
Algorithm 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- Integer specifying the life span (in seconds) of the public key. At the end of the
Public-Key- specified time, the key expires, and the server generates a new key. The default is
Expire 86400 seconds (24 hours).
Encrypt- Integer indicating whether encryption is on or off. Values are

Security-Policy
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- Size of the hash table that holds the encrypted session information. The default is
Session-Hash- 509; there is no maximum.
Entries 2
Encrypt- Integer specifying the life span (in seconds) of the data key. At the end of the
Symmetric- specified time, the key expires, and a new key exchange occurs. The default is 2700
Data-Key- seconds (45 minutes).
Expire
Escalation- Full path name of the file to use if escalation logging is on (See Debug-mode).
Log-File
Event- Enables the subscriber to receive the event as soon as a CI is created, updated, or
Channel- modified.
Enabled1
Exception- Integer value controlling the diagnostic output when the server crashes. Values are
Diagnostic-
Option 2 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- Mapping of LDAP groups to BMC Remedy AR System groups for external
Authentication- authentication. The value of this option consists of one or more pairs of group
Group- names separated by semicolons. For example:"LDAP-1" "ARS-1";"LDAP-2"
Mapping 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- Flag used by AR System during external authentication. Values are

Authentication-
Ignore-Excess- 0 — (Default) Users are authenticated when a match exists between every
Groups 2 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- Bit mask that specifies the return data capabilities for the current AREA plug-in. This
Authentication- option does not control the AREA plug-in; it merely describes the behavior of the
Return-Data- plug-in, enabling server optimization. Values are
Capabilities 2
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- RPC socket number on which an external authentication server awaits requests for
Authentication- authentication. The default value is 0 (external authentication is not used). The RPC
RPC-Socket program number for the plug-in server is 390695.
External- RPC timeout (in seconds) used when calling the authentication (AREA) server. The
Authentication- default value is 40 seconds.
RPC-Timeout
External- Internal timeout (in seconds) that the BMC Remedy AR System server uses to
Authentication- invoke the external authentication server's AREANeedToSyncCallback() function
Sync-Timeout 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- Time limit (in seconds) for the Filter API RPC to respond to the server's request
Timeout 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- Maximum number of recursion levels allowed for an operation. The data The Maximum Stack
Stack modification performed by an AR_FILTER_ACTION_FIELDP filter action might of Filters field in the
trigger a second set, or level, of filters, one of which might trigger a third level of Filters area on the
filters and so on. This option limits the number of times such recursion can happen, Advanced tab of the
preventing the server crash that would occur if the recursion continued indefinitely. AR System
The default value is 25. Administration: Server
Information form. (See
Setting performance
and security options)
Filter-Max- Maximum number of filters that the server executes for a given operation. The The Maximum Filters
Total default value is 10000. for an Operation field
in the Filters area on
the Advanced tab of
the AR System
Administration: Server
Setting performance
and security options)
Flush-Log- Flag indicating whether logged lines are buffered or written directly to disc. Values
Lines are:
T — (Default) Logged lines are written to disc.

F — Logged lines are buffered.
Full-Text-Case- Flag indicating whether full text searching is case sensitive or case insensitive. This The Case field in the
Option setting affects all fields indexed for full text search and affects how the indexes are Filters area on the FTS
built. Therefore, changes to this setting trigger an automatic re-index. Values are tab of the AR System

0 — Full text search is case sensitive Information form. (See

1 — (Default) Full text search is case insensitive FTS tab configuration
options)
Full-Text- Location in the file system where search engine index files are stored. The FTS Collection
Collection- Directory field on the
Directory 1 AR System
Administration FTS
Configuration form and
on the FTS tab of the
AR System
FTS tab configuration
options and FTS
Configuration form in
the AR System
Administration Console
.)
Full-Text- Location in the file system where search engine configuration files are stored. The FTS
Configuration- Configuration
Note: If you change the directory in this option, update the pluginsvr_config.xml
Directory Directory field on the
file with the correct directory path. This file is in ARSystemInstallDir\pluginsvr\fts.
AR System
Administration FTS
Configuration form and
on the FTS tab of the
AR System
options and FTS
Configuration form in
the AR System
.)
Full-Text- Flag indicating whether the server processes pending indexing tasks. Values are The Disable Full Text
Disable- Indexer field on the
Indexing T — Disable indexing. Pending indexing tasks are recorded for processing FTS tab of the AR
later when indexing is enabled. System Administration:
F — (Default) Do not disable indexing. Server Information
form. (See FTS tab
configuration options.)
Full-Text- Flag indicating whether the server uses the full text search engine for searching. The Disable Full Text
Disable- Values are Searching field on the
Searching FTS tab of the AR
T — Disable the full text search engine. The server uses the search capability System Administration:
of the underlying database whether or not a user has a full text license. Server Information
F — (Default) Use the full text search engine. form. (See FTS tab
Full-Text- Time, in milliseconds, used by the FTS Lucene index commit thread to decide the
Index-Commit- interval after which an index for an entry is committed in Lucene collections folder.
Interval
Default value is 60000 milliseconds (or 1 minute).

For example, consider Lucene commit thread runs at 10:45:23 AM. If the first entry
is created at 10:45:24 AM, the second entry is created at 10:45:45 AM and the third
entry is created at 10:46:21 AM. Then all the three entries are committed to Lucene
collections folder at 10:45:23 AM; that is 1 minute after the last entry is created.
Note: If the value of the Full-Text-Index-Commit-Interval is set to less than 2000

milliseconds (or 2 seconds), then the default value is set to 2000 milliseconds (or 2
seconds).
Full-Text- Full path name of the file to use if full text indexer logging is on (See Debug-mode).
Indexer-Log-
File
Full-Text- Delay in milliseconds before the scheduler provides a wakeup signal to the FTS
Index- controller to check for pending FTS entries that should be processed. For more
Scheduler- information, see How FTS indexing works (see page 1438).
Interval
Default value: 120000 milliseconds (120 seconds)
If the Full-Text-Index-Scheduler-Interval is set to a value less than 60000

milliseconds (1 minute), the Full-Text-Index-Scheduler-Interval is reverted to a
default value of 60000 milliseconds.
Full-Text- Number of minutes that the server waits between periodic attempts to index entries The Indexing Failure
Indexer- that failed to index for an unexpected reason in a prior attempt. The default value is Recovery Interval
Recovery- 60 minutes. field on the FTS tab of
Interval the AR System
options.)
Full-Text- The way the server modifies qualifications from the client. Values are The Search Options
Match-Option field on the FTS tab of
0 — Force leading and trailing wildcards. the AR System
1 — Ignore leading and force trailing wildcards. Administration: Server
2 — Ignore leading wildcards. Information form. (See
3 — Remove leading and trailing wildcards. FTS tab configuration
4 — (Default) Leave query unchanged. options.)
Full-Text- The maximum number of search results returned from the search engine. The The Full Text Search
Search- default value is 10,000. To limit the number of search results (because of Threshold field on the
Threshold constraints on the computer where the search engine is running), reduce the FTS tab of the AR
threshold. If you change this option, you must restart the BMC Remedy AR System System Administration:
server for the change to take effect. Server Information
form. (See FTS tab
Full-Text- During the processing of search results, the server combines results from The Complex Search
Search- subqueries to arrive at the final result set. If the number of rows created during Threshold field on the
Threshold- processing exceeds this value, the server returns an error message indicating the FTS tab of the AR
High search is too complex. The default value is 1,000,000. System Administration:
Server Information
form. (See FTS tab

Full-Text- While processing search results, the server creates a temporary table if the number The Temporary Table
Search- of FTS matches reaches this value. If the number of FTS matches is under this Threshold field on the
Threshold-Low value, the server uses the SQL IN operator for a query on an existing table. The FTS tab of the AR
default value is 200. System Administration:
Server Information
form. (See FTS tab
Full-Text- (Server groups only) Number of seconds before a signal is sent to the server that The Indexer Server
Signal-Delay owns the full text indexing operation (if no signal is pending). When a server is not Group Signal Delay
the owner of the full text indexing operation and generates indexing work, that field on the FTS tab of
server signals the server that is the owner of indexing. To reduce the frequency of the AR System
signals sent, the signaling is conducted on a delayed basis. When indexing is Administration: Server
generated, the server checks whether a signal is pending. If a signal is pending, the Information form. (See
server does not need to take any action. If a signal is not pending, the server FTS tab configuration
creates a pending signal to be sent in the specified amount of time. If the full text options.)
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- Flag indicating where to format the GetListEntry date. This option is used mainly
Server-Date- for backward compatibility purposes. Values are
Format 2
T — Format date on server.
F — (Default) Format date on client.
Guest- Flag indicating whether guest users receive a restricted read license when they log The Give Guest
Restricted- in to BMC Remedy AR System. Values are Users Restricted
Read Read field on the
T Configuration tab of
F the AR System
If this option is not specified, guest users receive a read license.
Setting administrative
options.)
GUID-Prefix 2 Character string used as a prefix for GUID strings generated by filters.
Homepage- Path to the systemwide default home page. This home page is used only if The Default Home
Form Form field on the
The current server is designated as the server for the home page in the BMC Configuration tab of
Remedy AR System User Preference form. the AR System
Or
The current server is designated as the home page server on the General Setting administrative
Settings page in Mid Tier Configuration Tool (See Configuring the General options.)
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- (Informix databases only) Name of the server where the underlying database is
DBServer- located.
Name 1
Informix-Relay- (Informix databases only) Environment setting for the path for the Informix relay
Module 1 module.
Informix- (Informix databases only) Name of the configuration file for the underlying database.
TBConfig 1 The default name is onconfig.
Internal-User- Number of shared, linked lists that hold all user-related information. This number
Info-Hash-Lists must be a power of 2. The default setting is 128. The minimum number is 2. There
2 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- Time, in minutes, that the AR System server waits before removing inactive user
Instance- instances from its internal memory cache. Use this option in an LDAP environment
Timeout 2 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.
Jmx-port1 Defines the JMX port number that enables administrators to connect to JVM by
using Java Messaging Extensions (JMX).
Default value: 61500
Large-Result- Allows you to monitor large memory allocations

Logging-
Default value 1000000
Threshold
License- Number of hours the BMC Remedy AR System server waits before disconnecting
Timeout inactive users. If a user is holding a floating license, the system also frees the
license. The default value is two hours.

Locale-List The installed language packs. Some sample values are
de — German
en — English
es — Spanish
fr — French
it — Italian
ja — Japanese
ko — Korean
pt_br — Brazilian Portuguese
ru — Russian
zh_cn — Simplified Chinese
Localized- A semicolon-separated list of message numbers used to modify the server's default
Messages-To- caching behavior for localized system messages.
Cache
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- Flag indicating whether the server is running in localized support mode. Values are The Localize Server
Server field on the Advanced
T — Run in localized support mode, and use localized messages if available. tab of the AR System
F — (Default) The server does not search for or use localized strings. Administration: Server
Setting performance
and security options.)
Locked- Mode that causes the server to record locked workflow actions in workflow logs.
Workflow-Log- These actions are written as encrypted strings.
Mode 2
Log-DSO- Flag indicating whether to log failed pending distributed operations to the Distributed
Errors-To- Pending Errors form. Values are
Form
T — Log errors to the form.
F — Do not log errors to the form.
Log-DSO- Flag indicating whether to include a list of source entry field/value pairs for errors
Field-Values 2 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- Flag indicating whether to create a separate *.bak file or to append to the existing
Append log file. Values are
T — Append new log information to the existing file.

F — (Default) Create a *.bak file.
Log-Form- Bitmask indicating the type of information to log in the common log form (AR System
Selected 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 theDebug-mode option). To activate two or more
bits, add their values, and set this option to the total. For example, to activate bits 1
and 3, set this option to 5 because bit 1 has a value of 1 and bit 3 has a value of 4.
To deactivate a bit, subtract its value from the value of this option. This option does
not apply to the following bits because no log form is created for their corresponding
applications:

Long-Running- The minimum number of seconds to complete an escalation before a line is added
Escalation- to the thread log to detail how long the escalation ran. See Using logs to identify
Logging- long-running escalations (see page 4359).
Threshold
Map-IP- IP address mappings that enable alerts to work through firewalls when Network
Address 2 Address Translation (NAT) is on. You must set up a mapping for each client
computer that has access through the firewall where the client IP address is
translated from an internal address to a valid external address. In addition, a
mapping is required for the AR System server IP address if the host where the
server resides is also translated. Here is a multiple line example:
Map-IP-Address: 123.45.67.89 10.5.119.83

Map-IP-Address: 123.45.55.90 10.26.55.65
Max-Entries- Maximum number of requests returned by a search. Because users can also specify The Max Entries
Per-Query the maximum number of requests returned through Search Preferences in the BMC Returned by GetList
Remedy AR System User Preference form, the actual maximum is the lower of field on the
these values. The default value is no server-defined maximum. Configuration tab of
the AR System


BMC recommends always setting a value for this parameter as unqualified searches Setting administrative
can yield enormous results resulting in unpredictable system behavior.
options.)
Max-Log-File- Maximum size in bytes for system log files. If the maximum is reached, the logging
Size 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- Maximum number of backup (.bak) log files to be allowed when the log file reaches
History 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- Maximum number of bytes that can be in a line of a mail notification.

Mail-Line-Len 2
Max- Maximum number of consecutive bad password retries a user can make. If this The Max Number of
Password- option is set to 3, the user has 3 chances to log in. If all 3 attempts have bad Password Attempts
Attempts passwords, the user account is markedINVALID. Values are 0 (which turns this field on the
feature off) and all positive integers. Configuration tab of
the AR System
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.)
options.)
Max- For forms that contain hierarchical data, such as manager and employee The Maximum Depth
Recursion- relationships, the maximum number of levels in the hierarchy that a recursive query for Hierarchical Query
Level retrieves. Values are any integer greater than 0. The default is 25. (See field on the Advanced
ARGetListEntryWithMultiSchemaFields.) tab of the AR System
Setting performance
Max-Vendor- Maximum number of temporary tables that can exist on an AR System server for a The Maximum Vendor
Temp-Tables single vendor form. The ARGetListEntryWithMultiSchemaFields function stores Temp Tables field on
data from vendor data sources in these tables. By default, only one temporary table the Advanced tab of
can exist for each vendor form. This setting applies to all vendor forms on the the AR System
server. It is overridden by the value of an individual vendor form's Maximum Vendor Administration: Server
Temp Tables property. Enter any integer greater than 0. (See Information form. (See
ARGetListEntryWithMultiSchemaFields.) Setting performance
Max-Log- Allows you to create maximum eight backup log files. Each log file will be of the size
History defined in the Max-Log-File-Size parameter.
Default value:8
Max-Log-File- Allows you to set the size of backup file.

Size
Maximum- Maximum number of concurrent client-managed transactions. The default is 10, and
Concurrent- the maximum value you can enter is 100.
Client-
Managed-
Transactions

Mid-Tier- Password that administrators use to access the mid tier. The Mid-Tier
Service- Administrator
Password Password field on the
Connection Settings
tab of the AR System
Setting server
passwords, RPC
options, and plug-in
timeouts.)
Minimum-API- Oldest API version with which the server communicates. The default value is 0, Maps to: The
Version which means that the server communicates with all API versions. If the client's API Minimum API Version
version is less than the specified value, the server refuses to talk with the client, and field on the
the client receives a decode error. (A AR System client is any program that Configuration tab of
accesses the AR System server through API calls, for example, BMC Remedy the AR System
Developer Studio, plug-ins loaded by the plug-in server, and so on.) Administration: Server
options.)
Minimum- Oldest CMDB API version with which the server communicates. The default value is
CMDB-API- 3. If the version of a CMDB call is less than the specified value, the server refuses
Version the call. This option is independent of the Minimum-API-Version option.
Multiple- Flag indicating whether other AR System servers can run on this server's host
ARSystem- computer. Values are
Servers
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 toT. Otherwise, the 7.5.00 or later server installation will
fail.
Multiple- Flag indicating whether multiple assignee groups can be stored in row-level security The Enable Multiple
Assign-Groups field ID 112. This enables users from multiple groups to access the same request. In Assign Groups field
the past, only one group could be stored in Field 112. Values are on the Configuration
T — (Default) Allow multiple groups in field ID 112. Administration: Server
F — Do not allow multiple groups in field ID 112. Information form. (See
options.)
is-ZDT You need to add this parameter to perform zero downtime upgrade of the platform
components.
T — Allows zero downtime upgrade.
2. Options you cannot set or view using the AR System Administration: Server Information form

ar.cfg or ar.conf options N-R
Note
Settings N-R (see page 1216).
N through R.
ar.cfg (ar.conf) file options (N-R)
Tips
text box.
For example, to search for the Next-ID-Block-Size parameter, select it from the
For example, to search for all ID parameters, type ID in the Option text box.
For example, to search for the parameters which have Configuration in the
description, type Configuration in the Description text box.
Next-ID- Flag indicating whether to perform a new commit transaction when the system
Commit 2 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- Option that allocates next IDs in blocks instead of one at a time. Allocating in The Next Request ID
Block-Size blocks increases performance during create operations. Values are any positive Block Size field on the
number up to 1000. The default value is 25. (A value of 1 disables the feature.) Configuration tab of the
You can also disable it by removing it from the configuration file. You do not need AR System
to restart the server for the change to take effect. Administration: Server
This setting is always disabled on the Distributed Pending form so that DSO can Information form. (See
operate correctly. Setting administrative
options.)
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- Base URL that appears in email notifications. If this option is not used, the Default-
Web-Path 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- Total number of preload segments loaded by the preload threads when preload The Number of Preload
Schema- threads are configured. SeeSetting the Preload Tables Configuration option. Segments field on the
Segments Advanced tab of the AR
System Administration:
(See Setting performance
Num-Preload- Number of preload threads to use when preload threads are configured. A value of The Number of Preload
Threads 0 indicates that preload threads are not used. The maximum value is 30 or twice Threads field on the
the number of preload segments, whichever is lower. See Setting the Preload Advanced tab of the AR
Tables Configuration option. System Administration:
Num- Defines the number of threads that can be used to monitor all the live client socket
selector- connections for IO activity. When the thread detects any activity, it forwards the
threads1 call to the appropriate queue.
Default value: 1
Oracle-Bulk- Number of data rows simultaneously fetched from the result set when an Oracle
Fetch-Count database is queried. The minimum is 1, the maximum is 100, and the default is 50.
2 The higher the value, the more memory is used during data retrieval.
Oracle-Clob- (Oracle databases only) Flag controlling Oracle CLOB storage. Values are
Storage-In-
Row 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- Database setting that matches the setting in the Oracle initialization file (initARS.
Cursor- ora if the BMC Remedy AR System database SID is ARS). Values are
Sharing 2

FORCE — Use this value if the initARS.ora file includes the following line:
CURSOR_SHARING=FORCE. This value is not recommended.
EXACT — Use this value, if your Oracle database is set to perform case
insensitive search or case sensitive search. This is the recommended value
for BMC AR System 9.0 and later.
Default value: FORCE (AR System 9.0.0 only)
Default value: EXACT (For AR System 9.0 SP1 and later)
Oracle- Option that enables BMC Remedy AR System to support remote databases with
Dblink- different character sets. You can enter this option multiple times in the
Character- configuration file for multiple view forms on different remote databases with
Set2 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- Flag indicating whether CLOBs can be searched. Values are

Search-On-
Clob 2 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- (Oracle databases only) Service Name for the underlying database.
Service
Overlay- Specifies the default overlay group for the server. Clients that use the default
mode2 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.
Peer-listener- Defines the port number where all the cache instances from different servers
port1 communicate with each other.
Per-Thread- Flag indicating whether to create per-thread log files. Values are
Logging
T — Create per-thread log files.

F — (Default) Do not create per-thread log files.
Plugin 2 File name of one or more plug-ins that the plug-in server loads. The file name of
the DLL or shared object is provided. The file name might be an absolute file name
or might be relative to the BMC Remedy AR System installation directory. Add as
many entries for this option to the server configuration file as needed, but specify
only one file name in each option.
Note: This parameter is for the running C plugins in the C plugin server.
Plugin- Number of threads dedicated to handling ARDBC requests from the BMC Remedy
ARDBC- AR System server. You must specify a minimum number. Optionally, you can also
Threads 2 specify a maximum number (the plug-in server increases the number of threads for
a plug-in as needed up to the specified maximum). The syntax is
Plugin-ARDBC-Threads: <minimumNumberOfThreads>[<maximumNumberOfThreads>]
By default, 1 thread is initiated if this option is not specified.
Note: Plugin-ARDBC-Threads parameter is used by the C plugin server. This

parameter is not used by Java plugin servers. For Java plugin server, you can
change the number of threads by changing the value of the numCoreThreads tag
in pluginsvr_config.xml file.
Plugin-AREA- Number of threads dedicated to handling AREA requests from the BMC Remedy
Threads 2 AR System server. You must specify a minimum number. Optionally, you can also
specify a maximum number (the plug-in server increases the number of threads for
a plug-in as needed up to the specified maximum). The syntax is
Plugin-AREA-Threads: <minimumNumberOfThreads> [<maximumNumberOfThreads>]
Note: Plugin-AREA-Threads parameter is used by the C plugin server. This

Plugin- Flag indicating whether the plug-in server accepts calls from remote servers.
Disable- Values are
Remote 2
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- Number of threads dedicated to handling BMC Remedy AR System Filter API
API-Threads requests from the BMC Remedy AR System server. You must specify a minimum
2 number. Optionally, you can also specify a maximum number (the plug-in server
increases the number of threads for a plug-in as needed up to the specified
maximum). The syntax is
Plugin-Filter-API-Threads: <minimumNumberOfThreads>
[maximumNumberOfThreads>]

Note: Plugin-Filter-API-Threads parameter is used by the C plugin server. This

Plugin-Log- Full path name of the file to use if plug-in logging is on (see Debug-mode).
File
Note: This parameter is for C plugin server. For more information on Java plugin
logging, see Setting plug-in server options (see page 361).
Plugin-Log- Option that specifies the type of information printed to plug-in log files. Values are
Level
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- RPC socket number for the private server queue to which loopback plug-in API The Plugin Loopback
Loopback- calls should be directed. Values are in the following ranges: RPC Program Number
RPC-Socket field on the Ports and
390621-390634 Queues tab of the AR
390636-390669 System Administration:
390680-390694 Server Information form.
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- Plug-in password. If this option is specified, the plug-in server accepts connections
Password only from BMC Remedy AR System servers whose Server-Plugin-Target-
Password option is set to the same password. If this option is not specified, the
plug-in server accepts connections from BMC Remedy AR System servers that are
not configured to use a plug-in password.
Plugin-Path 2 Search path used to load a plug-in. The path is appended to the current value of
LD_LIBRARY_PATH (AIX, Linux, Oracle Solaris), SHLIB_PATH (HPUX), or PATH
(WINNT). Multiple paths can be specified for this option; each path is appended in
the order it appears in the configuration file. The syntax is
Plugin-Path: <pathName> [<delimiter>]\[<pathName>]
Insert no spaces between the delimeter and the path. For example: UNIX
Plugin-Path: /usr/ar/bin:/usr/ar/common/xyz

Windows
Plugin-Path: C:\Program Files\AR System\arserver;

C:\Program Files\BMC Remedy AR System\common\xyz
Plugin-Port 2 The port number on which the plug-in server waits for incoming requests.
Preference- Option that specifies whether users must use centralized preferences. Values are The Preference Server
Server- Option field on the
Option 1 — Users can choose to use a preference server if one is available. Advanced tab of the AR
2 — Users must use the specified preference server. System Administration:
3 — Users must use a preference server, but they cannot use this server as Server Information form.
a preference server. If users choose a server that is not a preference (See Setting performance
server, a warning is returned. and security options.)
Preload-At- Flag indicating when preload threads (if configured) are used. Values are The Preload Tables At
Init-Only Init Only field on the
T — Preload threads are used only during server startup. Advanced tab of the AR
F — (Default) Preload threads are used whenever the cache is loaded from System Administration:
the database. Server Information form.
For information about how to determine whether to use preload threads, see
Setting the Preload Tables Configuration option.
Private-RPC- RPC program number that determines the type of queue to which requests are The Server Queue field
Socket routed and the number of threads running on that queue. on the Ports and Queues
Setting ports and RPC
numbers.)
Private-RPC- Option that designates debug queues. A debug queue is a type of private queue
Socket (for used by the BMC Remedy AR System Workflow Debugger. To make any private
debug queue) queue a debug queue, use this syntax:Private-RPC-Socket: rpcNumberDebug
For example: Private-RPC-Socket: 390666 Debug Alternatively, you can make a
private queue a debug queue by selecting its Debug check box in the list of
queues in the Ports and Queues tab of the Administration Console.
RE-Log-File- Location of the Reconciliation Engine log file.

Location 2
For more information on modifying the reconciliation engine system parameters,
see Configuring Reconciliation Engine system parameters.
Read-Only- Option that causes BMC Remedy AR System not to create database transactions
Tran-Off 2 when only reading data.
The default value is (T) true.
This setting is applicable for SQL Server and Sybase databases only.
Flag indicating whether the BMC Remedy AR System server records the
relationships between workflow objects.

Record- Note: If using a server group, all servers within the same server group must have The Record Object
Object- the same setting for this option. If they do not, the servers in the group Relationships field on the
Relationships inconsistently populate and un-populate the object relationship database should Configuration tab of the
they be the highest ranked server for the Administration operation when they are AR System
restarted. Only the highest ranked server for the Administration operation in the Administration: Server
server group will perform the required object relationship actions when restarted. Information form. (See
Values are
options.)
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, the server records the relationships of all server
objects before it accepts connections from clients. Therefore, the first time you set
the value to T, you cannot connect to the server by using any client temporarily.
The more the number of objects defined on the server, the more time it takes to
connect to the server. With a large number of objects, such as with an ITSM
application installed, and depending on the performance of the database, this
could take up to an hour. When you can reconnect to the server, the recording of
object relationship data is complete.
F — (Default) The server does not record relationships.
When you set this option to F or clear it, all the recorded relationships are deleted
from the database.
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 to log in the Server Events form, which makes server-related
Server- changes available to workflow and API programs. Enter the following values,
Events 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- Flag that prevents the BMC Remedy AR System server from registering with a The Register with
With- portmapper. Use this feature in conjunction with setting specific ports to enable Portmapper field on the
Portmapper you to run servers on computers that do not have a portmapper. Values are Configuration tab of the
AR System

T — (Default) Register with portmapper. Administration: Server

F — Do not register with portmapper. Information form. (See
Setting ports and RPC
No more than one server should try to register with AR System Portmapper in an numbers.)
environment with multiple servers on one computer.
Registry- Password of the BMC Atrium Web Services Registry admin user. Used by
Admin- workflow for the BMC Remedy AR System Web Services Registry form.
Password
Registry- User name of the BMC Atrium Web Services Registry admin user. Used by
Admin-User workflow for the BMC Remedy AR System Web Services Registry form.
Registry- URL of the BMC Atrium Web Services Registry. Used by workflow for the BMC
Location Remedy AR System Web Services Registry form.
Rejected-By- Specifies the interval in months or days for which a user wants to see all the
Others- requests rejected by others.
Interval1
Remedy-App- Encrypted password that AR System application services such as Approval Server The Application Service
Service- use to access the BMC Remedy AR System server. Password field on the
Password Connection Settings tab
of the AR System
Setting server passwords,
RPC options, and plug-in
timeouts.)
Required- Character to add to the label of a field whose entry mode is Required. The default The Required Field
Field- is an asterisk. Identifier field on the
Identifier Configuration tab of the
AR System
options.)
Required- Position to add the character that identifies a Required field. Values are The Required Field
Field- Identifier field on the
Identifier- 0 — Add the character to the beginning of the field label. Configuration tab of the
Location 1 — (Default) Add the character to the end of the field label. AR System
options.)
Restrict-Log- A list of semicolon-separated client types (or IDs if the client type is not known).
Client-Type Restricts logging only for specified client types.
For example, Mid-tier;Developer Studio;Remedy Administrator
Restrict-Log- Restrictions are applied to the API, SQL, and Filter logs only for specified RPC
RPC-Queue Queues.
For example, 390600;390680;390620

Restrict-Log- A list of semicolon-separated user names. Restricts the logging only for specified
Users users.
For example, Allen;Mike
Restrict- Controls which type of logging restriction is enabled. The value of the Restrict-
Logging Logging parameter depends on the combination of logging restrictions that you
select.. Possible values of the restriction parameters are as follows:
Users — 1
Client Type — 2
RPC Queues — 8
You can have combinations of Users, Client Type and RPC Queues restrictions.
For example, if you select Users and Client Type restrictions, the value of the
Restrict-Logging parameter is set to 9 (1+8).
Notes:
The default value of Restrict-Logging parameter is 0.

The Restrict-Logging parameter has an additional reserved value of 4.
RPC-Non- Flag that enables BMC Remedy AR System on compliant systems to receive
Blocking-IO 2 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
Note
Settings S-Z (see page 1226).
This section of the table includes the options for the ar.cfg (ar.conf ) file that begin with the letters
S and Z.
ar.cfg (ar.conf) file options (S-Z)
Tips
text box.
For example, to search for the SCC-Enabled parameter, select it from the Option
list, or type the parameter name in the Option text box.
For example, to search for all SCC parameters, type SCC in the Option text box.
For example, to search for the parameters which have NOLOCK in the description,
type NOLOCK in the Description text box.
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.
SQL-Server- To enable the multi-subnet failover parameter for Microsoft SQL server database failover
Always-On
T- Set the multi-subnet failover parameter.
F- Disabled (Default)
SCC-Comment- Flag indicating whether a source code control integration requires you to enter a comment
Checkin at checkin. Values are
0 — (Default) No comment is required.

1 — A comment is required.
SCC-Comment- Flag indicating whether a source code control integration requires you to enter a comment
Checkout at checkout. Values are
0 — (Default) No 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- Flag indicating the level of source code control integration. Values are
Integration-
Mode 0 — (Default) Advisory level.
1 — Enforced level.
SCC-Provider- Name of the source code control provider. For example: Visual Source Safe.
Name
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- Text to use in a query hint in the WITH clause of a SELECT statement when queries are
Hint 2 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- Name of the computer where the AR System server is installed. By default, a server in a
Connect-Name server group uses a fully qualified server name with domain to identify itself. Others servers
2 in the group use this name to communicate. To change the server name, add this option to
the configuration file:
Server-Connect-Name: <myComputerName.

Server-Connect-Name: <myComputerName.domain.com>
If a common server alias is specified, this option is required.
This name must be resolvable by DNS and is used exactly as specified. (See Configuring
server groups.)
Server- Full path name of the AR System data directory. This directory contains support and log
directory1 files for the AR System server.
Server-Group- Port number (RMIPort ) for email administration in Email Engine. If RMIPort is different
Email-Admin- from the default (1100 ), set this option to the new, port number to enable the server to
Port 2 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- Port number (RMIRegistryPort ) for Flashboards administration in the Flashboards server.
Flashboards- If the default Flashboards port number is changed, set this option to the new port number
Admin-Port 2 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- Name and location of the server group trace log file. The default name is arsrvgrp.log. For
Log-File example: Server-Group-Log-File: c:\temp\servgroup.log
Server-Group- Flag indicating whether the server is a member of a server group. Values are T and F The Server
Member (default). Group Member
field on the
Configuration
tab of the AR
System
Administration:
Server
Information
form. (See
Setting
administrative
options.)

Server-Group- Method that a server in a server group uses to notify other members of the group about
Signal-Option 2 object definition cache changes. Values are
T — The server uses arsignald to notify other members about all object definition
cache changes.
F — (Default) The server uses a combination of signaling and database posting to
indicate that definition changes have occurred. The database postings are read by
other servers in the group at their preset check intervals. Because an intentional
delay is used to avoid multiple recaches, the servers do not recache until after a
check interval cycle that has no new recache signals.
The combined signaling and database posting method reduces server activity but does not
notify other servers as quickly as the 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. In a server group, Server-Name refers to the
load balancer name.
If you specify a value for this option, enter the value after the -h option when you use the
arreload command-line utility. Otherwise, arreload uses the default server name rather
than the name specified by this option. Do not specify a fully qualified name for this option.
For example, use alpha instead of alpha.remedy.com.
Note: If this server belongs to a server group and you use a common server alias, you
must also specify the Server-Connect-Name option. (See Server-Connect-Name.)
Server-Plugin- Alias of a plug-in server. When the BMC Remedy AR System server calls a plug-in server,
Alias 2 it must determine whether the plug-in server name is an alias. Aliases can direct the BMC
Remedy AR System server to access a plug-in server running on a different host or
listening at a specified port number. The syntax is
Server-Plugin-Alias: <aliasName> <realName> <hostName>[:<portNumber>]
Workflow (that is, references to AR Filter API and ARDBC plug-ins) references a plug-in
name. This name can be an alias. This enables you to run a plug-in on a remote host or to
run more than one instance of a plug-in on a host. For example, to run the RMDY.ARDBC.
XML plug-in on the remote host foo at port number 12345, add the following entry to the
AR System server configuration file: Server-Plugin-Alias: RMDY.ARDBC.XML RMDY.
ARDBC.XML foo:12345The alias and real plug-in names can be identical if you run the
plug-in on a remote host. To run more than one instance of the plug-in on the same or
different hosts, create different aliases that reference the same plug-in on its respective
hosts.
Server-Plugin- Number of seconds in which the plug-in server must respond to a call before an error is
Default- returned. The minimum value is 0. The maximum is 600. The default is 60.
Timeout
Server-Plugin- Encrypted password used to call a plug-in server. The BMC Remedy AR System server
Target- uses this password whenever it communicates with a plug-in server running on the
Password specified host and port. The syntax is {{Server-Plugin-Target-Password: <hostName>:
<portNumber>: <encryptedPassword>
Server-Side- For server-side table fields, the number of requests (or size of the chunk) that the server The Server
Table-Chunk- retrieves at one time from the database and stores in memory to process during filter or Table Field
Size filter guide actions. The server then retrieves, stores, and processes the next chunk until all Chunk Size
requests are processed. The value 0 causes the server to retrieve an unlimited number of field on the

requests. The default is 1000 requests. Specifying a lower value causes the server to Configuration
process smaller chunks, which reduces server memory use but results in slower tab of the AR
processing because the server must access the database many times, especially for large System
tables. Specifying a higher value causes the server to retrieve and process large chunks of Administration:
data and access the database fewer times. This results in improved performance at the Server
cost of increased memory use. Information
form. (See
Setting
administrative
options.)
Server-Stats- Interval (in seconds) at which the server records server statistics. The default is 60 The Recording
Rec-Interval seconds. Interval field
on the Server
Statistics tab
of the AR
System
Administration:
Server
Information
form.
Server-Stats- Server statistics recording mode. This option determines what information is recorded in The Server
Rec-Mode the server statistics form. Values are Recording
Mode field on
0 — (Default) Recording is off. the Server
1 — The server records only cumulative queue statistics (the sum of all the Statistics tab
individual queue statistics). of the AR
2 — The server records both cumulative and individual queue statistics. One entry is System
written for the cumulative statistics and a separate entry is written for each queue. Administration:
Server
To see the statistics, open the Server Statistics form. (See Server statistics for baseline
Information
data.)
form.
Set-Process- Number of seconds the BMC Remedy AR System server waits before ending a Set Fields
Timeout 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- (Microsoft SQL Server only) Flag indicating the type of authentication to use to connect
Connection BMC Remedy AR System to a Microsoft SQL Server database. Values are
T — Windows Authentication
F — SQL Authentication
SQL-Server- Option that causes the server to issue a SET ANSI_NULLS ON command.
Set-ANSI-
Defaults 2
Submitter- Flag indicating whether the Submitter field can be changed and whether the submitter of a
Mode 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- A series of zero or more message numbers (separated by spaces) that identify
warnings 2 informational or warning messages that the system should suppress. Only server warnings
and notes can be suppressed.
Sybase- (Sybase databases only) Alternative character set to use for communications between
Character-Set 1 BMC Remedy AR System and the underlying database.
Sybase-Server- (Sybase and Microsoft SQL Server only) Logical server name of the underlying database.
Name 1 The default value is SYBASE.
System- Bitmask that sets logging options for the operating system. Values are
Logging-
Options 2 0 — (Default) Use normal operating system logging.
Bit 1 (value = 1 ) — Suppress logging to the operating system log file.
System- Flag to specify whether system messages appear in the prompt bar or a pop-up box.
Messages- Values are
Displayed
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- TCP port for the arserver process. If this option is not set, the dispatcher is randomly The Server
Port assigned to an available port. (TCD stands for transaction control daemon.) TCP/IP Port
field on the
Ports and
Queues tab of
the AR System
Administration:
Server
Information
form. (See
Setting ports
and RPC
numbers.)
Thread-Log- Full path name of the file to use if thread logging is on (See Debug-mode).
File
Track-Admin- Flag indicating whether the BMC Remedy AR System server populates progress
Op-Progress 2 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- Integer that specifies the cutoff year for interpreting a two-digit year as a four-digit year. For
Cutoff 2 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.
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- Controls whether the server will use full text searches when executing queries during The Use FTS
Workflow workflow that have full text indexed fields in the qualification. If this option is not used, the in Workflow
server will use the search capability of the database. The options are T (use FTS in field on the FTS
workflow) and F (do not use FTS in workflow). tab of the AR
System
Administration:
Server
Information
form. (See FTS
tab
configuration
options.)
Use-Password- Validation mechanism for unregistered AR System users. To set this value, use the
File 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- Flag indicating whether the server name specified by the Server-Connect-Name option is
Connect-Name- used as the value for the Server Name field when Server Statistics form entries are
In-Stats 2 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- Option indicating whether the object modification log is enabled or disabled. When the log The Object
Object- is enabled, it records every change to AR System objects in your system (See Version Modification
Modification- control in BMC Remedy AR System). Values are Log field on the
Log-Mode Version Control
0 — (Default) Disabled tab in the AR
10 — Enabled System
Administration:
Server
Information
form. (See
Setting version
control options
.)
VersionControl- Option indicating whether the AR System server writes a definition file each time an object The Save
Object- is created or changed (See Version control in BMC Remedy AR System). This option is Definition Files
Modification- effective only when the object modification log is enabled. Values are field on the
Log-Save- Version Control
Definition-Files 0 — (Default) Yes, a definition file is created. tab in the AR
10 — No, a definition file is not created. System
Administration:
Server
Information
form. (See
Setting version
control options
.)
VersionControl- Option indicating whether object reservation is enforced or disabled. When object The Object
Object- reservation is enforced, users can reserve server objects, and BMC Remedy AR System Reservation
Reservation- prevents other users from modifying the reserved objects (See Version control in BMC field on the
Mode Remedy AR System). Values are Version Control
tab in the AR
0 — (Default) Disabled System
10 — Enforced Administration:
Server
Information
form. (See
Setting version
control options
.)
Workflow- BMC Remedy Developer Studio provides the ENCRYPT and DECRYPT functions to encrypt
Encryption- and decrypt data in filters and escalations, securing the operations. By default, only the 56-
Algorithm 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.

XML-VUI- Flag indicating whether to export localized views when forms are exported in XML
Export-Default- definition format.
Is-Localized
Values are T and F.
Default value: F
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.
To create an ardb.cfg (ardb.conf) file (see page 1123)

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
}

armonitor.cfg or armonitor.conf
The Java-based armonitor.conf (armonitor.cfg) file is read by the armonitor (armonitor.exe)
binary, which runs the commands listed in the configuration file.
Note
Each file name is listed by its UNIX name. If a Windows equivalent exists, it appears in
parentheses after the UNIX name.
The armonitor configuration file is created at the following location:
(Windows) ARSystemServerInstallDir\Conf\armonitor.cfg
(UNIX) /etc/arsystem/serverName/armonitor.conf
armonitor configuration options
Note
Lines with a (#) sign in armonitor file are treated as comments and ignored.
The following table describes the armonitor configuration options:
Option Description
Environment- Defines environment values established for armonitor. You can include multiple instances of this option in the
variable file. Before initiating any processes, armonitor sets any values specified through this option in its environment.
Then, all processes that armonitor initiates inherit 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.
Syntax: EnvVariableName=value
Example: ARDATEONLY=MM/dd/yyyy
Monitor- Specifies the armonitor directory. Initially, the installer enters the location for the directory. This location to the
directory Monitor-directory is same as the location where BMC Remedy AR System is installed.
Related topic
armonitor (see page 1127)

AR System server components and external

utilities
This section describes some BMC Remedy AR System server components. Each item is listed by
its UNIX name. If a Windows equivalent exists, it appears in parentheses after the UNIX name.
AR System server components (see page 1127)

External utilities (see page 1136)
AR System server components

armonitor (see page 1127)

arplugin.exe or arplugin (see page 1130)
arserver (see page 1131)
arsystem (see page 1134)
Java plug-in server (see page 1135)
armonitor
The Java based armonitor starts and restarts the BMC Remedy AR System server, BMC Remedy
AR System plug-in server, Distributed Server Option (DSO) server, and processes specified in the
armonitor.conf (armonitor.cfg) file. The armonitor provides capability to:
stop a process
start a process that was stopped earlier by using the stop signal or that failed to start
restart a process
modify selective process
monitor the armonitor.conf file for changes made to individual processes
On Windows, armonitor automatically runs as a service called BMC Remedy Action Request
System Server.
On UNIX, the arsystem script usually controls armonitor. For more information, see arsystem
(see page 1134).
Note
Each file name is listed by its UNIX name. If a Windows equivalent exists, it appears in
parentheses after the UNIX name.

If a process terminates, armonitor restarts the server. If the server dies more than four times in 30
seconds, armonitor stops restarting that server.
The armonitor maintains the following lists for the processes specified in the armonitor.conf (
armonitor.cfg) file.
List Description
STARTED_PROCESSES_LIST Lists the processes that are currently running
FAILED_TO_START_PROCESSES_LIST Lists the processes which fail to start successfully
STOPPED_PROCESSES_LIST Lists the processes stopped by the user by using the stopprocess
<processname> API call (For more information see, armonitor.cfg or armonitor.conf
(see page 1126)).
Starting from BMC Remedy AR System 9.1, following enhancements are provided to armonitor
file:
ARMonitor.properties file (see page 1128)

ARMonitor_Admin.sh or ARMonitor_Admin.bat (see page 1129)
FILE_MONITOR (see page 1129)
ARMonitor.properties file
The ARMonitor.properties file consists of following properties to manage the BMC Remedy AR
System processes:
ARMonitor properties Description
com.bmc.arsys.armonitor. The RMI Port used by the ARMonitor_Admin to give instructions to armonitor. The
RMIPort property is configured by the armonitor file, when the process is started or restarted.
com.bmc.arsys.armonitor. Allows the armonitor file to detect the changes made to the armonitor.conf (armonitor.
filewatchenabled cfg) file without affecting other BMC Remedy AR System processes.
Default value: False
This preoprty can be set /unser to true/false throug \h the ARMonitor_Admin functions -
enablefilemonitor & disablefilemonitor
com.bmc.arsys.armonitor. Determines the maximum number of attempts that are made to enable the file-monitor
filewatchretrylimit
com.bmc.arsys.armonitor. timeout value in seconds, for which we will wait for receiving the startup signal from
server. server.
logintimeoutinseconds
If no signal received from server during this time, the server will not be considered as
started and the server process, if running, will be stopped.
com.bmc.arsys.armonitor. Determines the maximum number of attempts till a server is started before terminating the
server.startupretrylimit process.
com.bmc.arsys.armonitor. Determines the maximum number of attempts till a non-server process is started before
process.startupretrylimit terminating the process.

ARMonitor_Admin.sh or ARMonitor_Admin.bat
The ARMonitor_Admin.sh (ARMonitor_Admin.bat) file provides functionality to communicate
with the armonitor.conf (armonitor.cfg) file using the following API calls:
API call Description
isalive Checks if the armonitor.conf (armonitor.cfg) file is running
stoparmonitor Stops all the processes specified in the armonitor.conf (armonitor.cfg) file and stops armonitor.
conf (armonitor.cfg) file
getstartedprocess Lists all processes that are currently running
allprocessstatus Lists all processes sorted according to whether the process is successfully started, whether it failed
to start, or whether the user has stopped the process with ARMONITOR_ADMIN calls
stopprocess Stops the specific process if the process is currently running

<processname>
startprocess Starts a process if the process is not currently running

<processname>
restartprocess Restarts a process using the process name assigned to the process
<processname>
refreshprocess Refreshes the process with a new process definition read from the armonitor.conf (armonitor.cfg)
<processname> file
getprocesscommand Provides the process command assigned to the process.

<processname>
allprocessesdetails Provides the process details for all the processes specified in the armonitor.conf (armonitor.cfg)
file
isfilemonitorenabled Returns TRUE or FALSE based on whether the FILE_MONITOR option is enabled or disabled
enablefilemonitor Enables the FILE_MONITOR feature for armonitor and also updates the com.bmc.arsys.
armonitor.filewatchenabled property in the ARMonitor.properties file to True.
disablefilemonitor Disables the FILE_MONITOR feature for armonitor and also updates the com.bmc.arsys.
armonitor.filewatchenabled property in the ARMonitor.properties file to False.
FILE_MONITOR
Starting from BMC Remedy AR System 9.1 a new FILE_MONITOR feature is added to armonitor
to monitor the armonitor.conf (armontior.cfg) file for changes. The enablefilemonitor and
disablefilemonitor API calls are used to enable or disable the FILE_MONITOR feature.
The FILE_MONITOR provides following features when you modify the armonitor.conf (armontior.
cfg) file:
If a new process is modified, the process is started automatically without affecting other
processes running in the armonitor.conf (armontior.cfg) file.
If any numeric parameters of a process are modified, the same process is restarted by the
armonitor with the new parameter values.

Note
If you add a new parameter to an already running process, the armonitor considers this
as a new process and starts the process again. This creates two instances of the same
process running in armonitor which results in to error.
Related topic
armonitor.cfg or armonitor.conf (see page 1126)
arplugin.exe or arplugin
In this topic:
Description (see page 1130)

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 (see page ).
Synopsis
arplugin [-i ARSystemServerInstallDir] [-m] [-s serverName]
Options
You can specify the following options on the command line:
-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
In this topic:

Files (see page 1133)
Description
The arserver.jar executable 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.jar is usually started by armonitor which runs automatically as a service

called BMC Remedy Action Request System Server. Normally, you should use this service to
control arserver.
On UNIX, the arsystem script usually controls arserver.jar through armonitor. Normally, you
should use arsystem to start the arserver process (see arsystem (see page 1134)).
On UNIX systems, the arsignal command causes arserver to load or reload information (see
arsignal.exe or arsignal (see page 1141)). 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
c:\progfm\java\jdk\bin\java.exe[Java path ] -jar arserver.jar [-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.jar 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 (see page 4287).
Note
Running arserver.jar 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.
not set this variable, the system uses the date format specified in the Regional Settings of the user
account that runs the service.
ARDATEONLY, the system uses the date format for the language specified by the LANG variable.
ARTIMEONLY
Format used by the program for time-of-day fields.
not set ARTIMEONLY, the system uses the date format specified in the Regional Settings of the
user account that runs the service.
ARTIMEONLY, the system uses the time format for the language specified by the LANG variable.
LANG
(UNIX only) This value establishes the locale for BMC Remedy AR System, based on information
obtained during installation. Normally, this setting is managed by the arsystem script.
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
This topic describes the arsystem script, which is specific to UNIX environments only.

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,
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 (see page 1135)

Java plug-in server synopsis (see page 1136)
Java plug-in server options (see page 1136)
Java plug-in server files (see page 1136)
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

You can specify the following options on the command line:
-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 (see page 770).
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 (see page 1136)

arreload.exe or arreload (see page 1139)
arsignal.exe or arsignal (see page 1141)
ImageExtractor.jar (ImageExtractor.bat) (see page 1142)
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:
Option Description
-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

Option Description
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 (see page 1328) 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 System Administration: AR System
Configuration Generic UI form. 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 Configuration settings C-D (see page
1168).
arreload.exe or arreload
In this topic:
arreload description (see page 1139)

arreload scenarios (see page 1141)
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:
Options Description
-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

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 (see page 1080).) 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:
Option Description
-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. (see page 489)
-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:

Files (see page 1144)
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:
Input Description
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 Enter the name of the text file, if any, that lists the form names for which to convert images (see the
containing the Environment information). To convert all images on the AR System server, leave this option blank.
form names
Environment
You must have a supported Oracle Java runtime environment (JRE) installed and available in the
server environment.
To convert images for a specified list of forms, create a text file that contains one form name per
line. For example, the ImageExtractor utility would use the following text file to convert all images in
the Sample application forms listed:
Sample:Cities
Sample:ClassCentral
Sample:Classes
Sample:DialogYesNo
Sample:Enrollments
Sample:GetWeather

Files
ImageExtractor.jar
Configuration data is stored in the centralized configuration forms and reflected in the ar.cfg
configuration file (for backward compatibility). Centralized configuration not only simplifies the
management of configuration data, but also simplifies the sharing of configuration settings across
servers. Also, because configuration data is stored directly in the database, the data is more
secure.
The following topics provide detailed information about centralized configuration:
Backing up and restoring centralized configuration settings (see page 1145)

Centralized configuration system forms (see page 1146)
Configuration settings (see page 1147)
Notifications about changes to centralized configuration settings (see page 1235)
Updating configuration settings by using the AR System Configuration Generic UI form (see
page 1235)
The configuration data for the following components is centralized:

BMC Remedy Mid Tier
BMC Remedy Approval server
BMC Remedy Java plug-in server
BMC Remedy Shared (Shared parameters for all components)
BMC Remedy Distributed Server Option
BMC Remedy Flashboards server
BMC Remedy Assignment Engine
AR System Database Connectivity (ARDBC) LDAP plug-in
AR External Authentication (AREA) LDAP plug-in
Notes
You can continue to change the configuration settings for the following
components by using the listed form or tool:
BMC Remedy AR System server — AR System Administration:Server
Information form (see page 255)

BMC Remedy Approval Server — AP-Admin-ServerSettings form (see page

1718)
BMC Remedy Mid Tier — Mid Tier Configuration Tool (see page 393)
BMC Remedy Distributed Server Option — AR System Administration:
Server Information form (see page 544)
BMC Remedy Flashboards server — AR System Administration:
Flashboard Server Configuration form (see page 645)
BMC Remedy Assignment Engine — AR System Assignment Engine:
Server Settings form (see page 653)
You can use the AR System Administration:Plugin Server Information form (see
page 773) form to change the configuration settings for Java plug-in server.
You can use the AR System Configuration Generic UI form (see page 1235) form
for BMC Remedy Email Engine configuration settings and any other configuration
settings that are not available in the preceding forms.
page 773) form to change the configuration settings for ARDBC LDAP plug-in.
page 773) form to change the configuration settings for AREA LDAP plug-in.
Backing up and restoring centralized configuration settings

You can now maintain copies of your centralized configuration data and restore any copy to revert
to old customized settings at any time.
This topic provides the following procedures:
To create a backup (see page 1145)

To restore a selected backup (see page 1146)
To delete a selected backup (see page 1146)
Note
The backup functionality copies all the centralized configuration data. You cannot create
a component-specific or setting-specific backup.
To create a backup
> General > Centralized Configuration Backups.
2. In the AR System Configuration Backup Management form, in the Backup Name field,
enter a name for the backup.
3.
3. Click Backup.
Note
When you create a backup, the data is backed up in the following forms:
AR System Configuration Component_Backup

AR System Configuration Component-Setting Mapping_Backup
AR System Configuration Setting_Backup
To restore a selected backup
2. In the AR System Configuration Backup Management form, from the Available Backups
section, select the required backup, and click Restore Selected Backup.
When you restore a selected backup, it replaces all the current configuration settings with
the settings from the backup.
To delete a selected backup
2. In the AR System Configuration Backup Management form, from the Available Backups
section, select the required backup, and click Delete Selected Backup.
Centralized configuration system forms

In centralized configuration, configuration information is stored in the following system forms:
AR System Configuration Component form — Defines the name of the component (for
example, the server name) and the type of component. Examples of components are an AR
System server, a mid tier, Email Engine, and so on. The convention for naming component
types is similar to that of Java, for example, com.bmc.arsys.server.
AR System Configuration Setting form — Defines the configuration parameters for the
server.
AR System Configuration Component Setting form — Displays all of the properties of a

component. This join form contains data from the AR System Configuration Component and
AR System Configuration Setting forms.

Configuration settings
The centralized configuration forms contain the configuration settings or options for the following
components:

BMC Remedy Mid Tier
BMC Remedy Java plug-in server
BMC Remedy Shared (Shared parameters for all components)
When you change a configuration setting in the AR System Administration:Server Information form
(see page 255) (AR System server), the AP:Admin-ServerSettings form (see page 1718) (Approval
Server), or the AR System Administration: Plugin Server Information form (see page 357) (BMC
Remedy Java plug-in server), the configuration settings and their new values appear in the
centralized configuration forms. You can also change the configuration settings using the AR
System Configuration Generic UI form (see page 1235).
Notes
Changes to the ar.cfg (ar.conf) file for some settings are reflected in the
centralized configuration forms for backward compatibility, and changes to those
settings in the centralized configuration forms are reflected in the ar.cfg (ar.conf)
file .
BMC recommends that you update the configuration settings by using the UI
where possible.
For information about configuring mid tier properties, see Settings in the config.
properties file (see page 468).
For a list of all configuration settings, see:
Configuration settings A-B (see page 1148)

Configuration settings C-D (see page 1168)
Configuration settings E-M (see page 1201)
Configuration settings N-R (see page 1216)
Configuration settings S-Z (see page 1226)
Note

While upgrading the BMC Remedy AR System server, the value of the Configuration-
Name setting is mapped to the Server-Connect-Name setting. If the Server-Connect-
Name setting is not present, then the value is mapped to the Server-name setting.
Configuration settings A-B

The centralized configuration forms store the configuration settings. All the numeric values for the
settings are in base 10 system. You can modify the settings by using the AR System
Configuration Generic UI form. The settings are case- and space-sensitive. See Updating
Note
BMC recommends that you use the AR System Configuration Generic UI form to
modify the configuration settings. Do not use the ar.cfg file to modify the configuration
settings on the AR System Configuration Generic UI form.
The following table lists the settings available for centralized configuration.
Tip
If you cannot view all the columns, click Full screen in the upper-right corner
of the page to open it in full screen mode. Alternatively, use the scroll bar at the
bottom of the table.
To easily search for a specific parameter in the table, select the parameter from
the Setting list. Alternatively, type the name of the parameter in the Setting text
box.
Setting list, or type the parameter name in the Setting text box.
Configuration settings (A-B)

Setting 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.
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 be interpreted incorrectly. As AR System server does not
know which custom shell must be used for active link processing, it cannot supply all of the
necessary arguments. 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

Setting Description
4. In the AR System server configuration, change the Active-Link-Shell to be the new

program /usr/local/arsystem-csh-helper.
Admin-Only-Mode Flag indicating whether only administrators and subadministrators can access the server.
Valid values:
T — Admin-only mode is on.

F — (Default) Admin-only mode is off.
AE-Log-Enabled Flag indicating whether the Assignment Engine logging is enabled.
(Component name: com.bmc.arsys. Valid values:

assignment)
1 — (Default) Assignment Engine logging is disabled.
0 — Assignment Engine logging is enabled.
AE-Log-File AE-Logging-Level Indicates the type of logging level.

assignment)
(Default) INFO
DEBUG — The maximum logging level
ERROR — The minimum logging level
AE-Max-Log-File-Backups Indicates the 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.
(Component name: com.bmc.arsys.
assignment) Default value: 0

Setting Description
AE-Max-Log-File-Size Indicates the maximum size (in megabytes) for the log file.
(Component name: com.bmc.arsys. Default value: 10 MB

assignment)
AE-Poll-Interval 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 4 minutes.
assignment) Default value: 4 minutes
AE-Worker-Threads Indicates the total number of worker threads that process various assignment requests.
(Component name: com.bmc.arsys. Default value: 3

assignment)

Setting Description
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.
Valid values:
T — Allows the server to run a process with a backquote.

F (Default) — Does not allow the server to run a process with a backquote.
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).
Valid values:
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.
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 (
server)
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.
Valid values:
T — (Default) Allow unqualified searches.

F — Do not allow unqualified searches.
2 (see page 1168)

Alternate-Approval-Reg Flag indicating how applications such as Approval Server or Reconciliation Engine listen for
the BMC Remedy AR System server's signal.
approval) Valid values:
T — (Default) Listen for the application dispatcher to signal.

If your application relies on the application dispatcher, set this option to T. To verify
that arsvcdsp is configured to start with the BMC Remedy AR System server, check
the armonitor.cfg (armonitor.conf ) file.
F — Listen for the server's signal directly.
Note:
The BMC Remedy AR System server installation creates this entry and sets the value
to T.
You should change the value to F only when the application dispatcher is not working.
This provides an alternative method to receive signals from the AR System server.

Setting Description
AlwaysOn-Log-History Number of Always On log file backups that you need to store.
Default value: 2
API-Log-File Full path name of the file to use if API logging is on (see Debug-mode (see page 1186)).
API-Recording-Client-Type Indicates the client types for which you want to monitor the API calls. By default, this field
does not have any value set which means that the calls from all client types are monitored.
Use this format:
<clientType>;<ipAddressExpression>;<clientType>;<ipAddressExpression>
clientType — Indicates the client type to be monitor. This takes an integer value and a
* value in this field indicates that API calls from any client type are monitored. For
information on supported client types and their values, see Client types (see page )
.
ipAddressExpression — Indicates a regular expression used to match the source
address. This is an optional value to specify. If you do not specify any value, all
source addresses are matched by default.
For example, you might add the following values:
0;1;2 — API calls from client types 0, 1, and 2 (all source addresses are
matched).
0 ^10\..;1;2* — API calls from client types 1 and 2 included (all source
addresses are matched as the regular expression is not specified). API calls
from client type 0 included if the source address is from an IP address starting
with 10.
0;* ^(?!10\.) — API calls from client type 0 ("unknown") are recorded (all
source addresses are matched as the regular expression is not specified). API
calls from all clients with a source address that does not start with 10 are
included.

Setting Description
^(?!10\.)(?!11\.) — API calls from all clients with a source address that does
not start with 10 or 11 are included.
API-Recording-Enable Specifies whether you want to enable the system for monitoring API calls.
Valid values:
Yes — Indicates that monitoring is enabled.

No — (Default) Indicates that monitoring is disabled.
Approval-Debug-Type2 (see page 1168) This setting specifies the log level for approval server. Values are:
(Component name: com.bmc.arsys. 0 — (Default) The minimum logging level for BMC Remedy Approval Server is
approval) NORMAL (or INFO).
1 — The highest logging level for BMC Remedy Approval Server is ALL (or DEBUG).
Approval-Defn-Check-Interval 2 (see Interval (in seconds) at which Approval Server checks for changed or updated data in the
page 1168) data definition forms.

server)
Approval-Due-Soon2 (see page 1168) The duration after which the approval requests that are due for action are highlighted on
Approval Central.
approval)
Approval-Log-File 2 (see page 1168) Full path of the Approval Server log file.

server)
Approval-Notify 2 (see page 1168) Flag indicating whether approval notifications are configured from the Server Settings dialog
(Component name: com.bmc.arsys. box. An Approval-Notify entry exists for each ID.
approval)
Warning : Do not change this option in the AR System Configuration Component Setting
form . Instead, from the AP:Administration form, click the Server Settings link to open a
dialog box with configuration settings for the Approval Server.
Approval-Polling-Interval 2 (see page 1168 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
(Component name: com.bmc.arsys. configuration) contacts the Approval Server when work is pending. When this option is
approval) specified, the Approval Server polls the AR System server only if it does not receive a signal
from the AR System server in the specified time. Specify the interval in seconds. Minimum is
30 seconds. Maximum is 3600 seconds (one hour).
Approval-Recent-History2 (see page 1168) The duration within which a user can see in the recent history an approval request that was
submitted or acted upon.
approval)
Approval-RPC-Socket 2 (see page 1168) 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
(Component name: com.bmc.arsys. Server.
server)

Setting Description
AR-Max-Attach-Size 2 (see page 1168) 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
(Component name: com.bmc.arsys. the database, you can prevent excessive memory growth and reduce transmission time. This
server) limit does not apply to attachments retrieved from the database by the AR System server.
This option applies to all databases.
Note: To limit the size of compressed attachments that the server can retrieve from Oracle
databases, use Db-Max-Attach-Size.
ARDBC-LDAP-Base-DN Base distinguished name (DN) to use instead of the root DN as the starting point for
discovering vendor tables when you design vendor forms. For example: ARBDC-LDAP-
(Component name: com.bmc.arsys.ldap.
Base-DN: CN=Users, DC=ldapesslab, DC=com.
ardbc)
ARDBC-LDAP-Cache-MaxSize Size limit (in bytes) for the cache. For no size limit, set this to 0.
(Component name: com.bmc.arsys.ldap. Default value: 32768 bytes

ardbc)
ARDBC-LDAP-Cache-TTL Time limit (in seconds) that data remains cached. For no time limit, set this to 0.
(Component name: com.bmc.arsys.ldap. Default value: 60 seconds

ardbc)

Setting Description
ARDBC-LDAP-Cert-DB 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
(Component name: com.bmc.arsys.ldap. the BMC Remedy AR System installation directory for these files. The path in this option is
ardbc)
used only when ARDBC-LDAP-UsingSSL is set toT.
ARDBC-LDAP-Cert-Name 2 Not yet implemented.

ardbc)
ARDBC-LDAP-Chase-Referrals 2 Flag that enables automatic referral chasing by LDAP clients.
(Component name: com.bmc.arsys.ldap. Valid values:

ardbc)
T — Referrals are chased.
F — (Default) Referrals are not chased.
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
(Component name: com.bmc.arsys.ldap. maximum value is the External-Authentication-RPC-Timeout setting. If a value is not
ardbc) 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.
ardbc) Default: 3600 seconds
ARDBC-LDAP-Drop-Large-Values 2 Obsolete in version 7.0.00 and later.

ardbc)
ARDBC-LDAP-Hostname Host name of the system on which the directory service runs. If the host name is not
specified, the ARDBC LDAP plug-in uses localhost as the host name. For example:ARDBC-
LDAP-Hostname: server1.eng.remedy.com
ardbc)
ARDBC-LDAP-Key-DB 2 Not yet implemented.

Setting Description
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
(Component name: com.bmc.arsys.ldap. client when processing a search request containing the pagedResultsControl. The
ardbc) maximum value is 100,000. The minimum value is 100. (See Using the ARDBC LDAP plug-in
.)
Default value: 10,000
ARDBC-LDAP-Port Port number on which the directory service listens for clients.

ardbc)
ARDBC-LDAP-Time-Format 2 Format of LDAP date and time data.

ardbc)
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
(Component name: com.bmc.arsys.ldap. requests are satisfied from the cache.
ardbc)
ARDBC-LDAP-User-DN 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
ardbc)
ARDBC-LDAP-UsingSSL 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.

Setting Description

ardbc)
AREA-LDAP-Bind-Password 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
(Component name: com.bmc.arsys.ldap. plug-in uses an anonymous login to find the user object. If the target directory service does
ardbc) not allow anonymous access, you must specify a DN and password; otherwise, the plug-in
cannot determine the DN of the user.
AREA-LDAP-Bind-User Distinguished name (DN) of the user account that the AREA LDAP plug-in uses to find the
user object when using the User Search filter. If the DN is not specified, the AREA LDAP
(Component name: com.bmc.arsys.ldap. plug-in uses an anonymous login to find the user object. If the target directory service does
area) 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
AREA-LDAP-Cert-DB 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
(Component name: com.bmc.arsys.ldap. the BMC Remedy AR System installation directory for these files. This path is used only
area)
when ARDBC-LDAP-UsingSSL is set to T.

Setting Description
AREA-LDAP-Chase-Referral 2 Flag that specifies whether referral chasing is performed by the AD server or the AREA
LDAP plug-in.
area) Valid values:
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).
Note: To force referral chasing logic to be disabled, you must also specify the AREA-LDAP-
Disable-Referral option.
AREA-LDAP-Connect-Timeout 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
(Component name: com.bmc.arsys.ldap. value is the External-Authentication-RPC-Timeout setting. If a value is not specified, this
area)
option is set to the value of the External-Authentication-RPC-Timeout option (by default,
40 seconds).
AREA-LDAP-Disable-Referral 2 Flag that disables all referral processes by the AREA LDAP plug-in.

area)
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
(Component name: com.bmc.arsys.ldap. specified, the specified default or a system default is applied.
area)
AREA-LDAP-Email-Default 2

Setting Description
(Component name: com.bmc.arsys.ldap. Value that the AREA LDAP plug-in uses if the AREA-LDAP-Email parameter is not specified
area) or has no value for the user.
AREA-LDAP-Group-Base Base of the LDAP directory to search groups from. To determine the option's values at
runtime, use these keywords:
area) Note: The backslash (\) is required.

$\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.
System server.
AREA-LDAP-Group-Default 2 Default groups to which the user belongs if no group information is available from the
directory service. If the user belongs to multiple groups, use a semicolon to separate them.
area)
AREA-LDAP-Group-Filter LDAP search filter used to locate the groups to which the user belongs. To determine the
option's values at runtime, use these keywords:

$\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.
they log in.
System server.
AREA-LDAP-Hostname 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.
area)

Setting Description
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
(Component name: com.bmc.arsys.ldap. attribute is not specified, the specified default or a system default is applied.
area)
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)
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)
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)
AREA-LDAP-LicFTS Name of the attribute that identifies the type of FTS license assigned to the user. If the
attribute is not specified, the specified default or a system default is applied.
area)
AREA-LDAP-LicFTS-Default Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicFTS attribute is not specified
or has no value for the user.
area)
AREA-LDAP-LicMask Attribute that specifies how to mask the license information returned from the AREA LDAP
plug-in. Values are
area) 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.

Setting Description
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.
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)
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)
AREA-LDAP-LicRes1-Default 2 Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicRes1 attribute is not
area)
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
(Component name: com.bmc.arsys.ldap. form. If the attribute is not specified, the specified default or a system default is applied.
area)
AREA-LDAP-Notify-Meth-Default 2 Value that the AREA LDAP plug-in uses if the AREA-LDAP-Notify-Meth attribute is not
area)
AREA-LDAP-Port Port number on which the directory service listens for clients.

area)
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
(Component name: com.bmc.arsys.ldap. opening the secure connection. If you set AREA-LDAP-SSL-AUTH-OPTION to false, the
area) server certificate is not authenticated and multiple secure server connections can be
established concurrently.

Setting Description
AREA-LDAP-Use-Groups Flag indicating whether to retrieve group information from the LDAP server. If this parameter
is not set, group information from the AR System Group form is used.
area)
AREA-LDAP-User-Base 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
they log in.
System server.
AREA-LDAP-User-Filter 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:
area)

$\DN$ — User's distinguished name. This only applies to the Group Base Name and
they log in.
System server.
AREA-LDAP-UseSSL 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
(Component name: com.bmc.arsys.ldap. of the certificate database used to establish the connection.
area)

Setting Description
Arerror-Exception-List 2 (see page 1168) List of errors that trigger a dump of the current stack in the arerror.log file. Separate each
error number with a semicolon (for example, 123;345;).
ARF-Java-VM-Options 2 (see page 1168) Java command options for a virtual machine (VM). The options are documented in the online
AR System Java API documentation.
Archive-Interval Specifies the number of hours scheduled to run the global archive for all forms.
In a server group environment:
1. This configuration setting is shared among all the servers.

2. If you set this parameter on any of the server, it will be applicable for all the servers.
For information about setting, archive interval, see Setting global archive interval for forms
(see page 1904).
arsystem.authentication_server Server that the BMC Remedy Mid Tier uses to authenticate a user. If an authentication
server is specified, the mid tier authenticates with the specified server. The authentication
server must already be in the list of mid tier servers on the AR Server Settings page.
arsystem.enableSkins Flag that indicates whether skins are enabled on the BMC Remedy Mid Tier.
Valid values:

Setting Description
true (Default)
false
arsystem.homepage_server BMC Remedy AR System server that contains the home page that you want to open when
the user logs on. The home page URL is: http://midTierServer/contextPath/home The home
page server must be added to the list of mid tier servers in the AR Server Settings page. The
mid tier searches the designated server for the home page. If you have not selected a home
page server in the AR System User Preference form, the home page server specified in the
AR Server Settings page is used globally. A home page server specified in the AR System
User Preferences form takes precedence over the server set in the AR Server Settings page.
arsystem.licenserelease_timeout Number of seconds before BMC Remedy Mid Tier releases an AR System license for a user,
if the user does not log out of mid tier correctly.
Note: To log out correctly, the user must close the last browser window associated with the
current HTTP session or navigate away from the mid tier.
Default value: 60 seconds
arsystem.log_backups Maximum number of BMC Remedy Mid Tier backup log files that the system will generate
when the log file size exceeds the limit specified in the Maximum Log File Size (arsystem.
log_filesize).
Default value: 100
arsystem.log_category Type of information that should be stored in the BMC Remedy Mid Tier log file.
Valid values:
Reporting — Messages related to reporting

Cache — Messages related to definitions, such as forms and active links in the cache
Session Management — Messages related to user session construction and
expiration, such as logon, logout, or timeout
Configuration — Messages related to the config.properties file, such as when it is
loaded and changed
Flashboards — Messages related to Flashboards
Web Services — Messages related to web services
Field — Messages related to fields
Workflow — Messages related to compilation of workflow (primarily active link
actions), such as invalid active links
Performance — Messages related to performance, including duration of operations

Setting Description
Qualifications and Expressions — Messages related to parsing and compilation of

expressions, for example, in active links
Servlet — Messages related to servlet handling of http requests, primarily for
reporting results of back-channel requests
Internal — Internal logging messages
ARServer (API/Filter/Database) — Messages related to APIs, filters, and databases.
Selecting the ARServer (API/Filter/Database) option, overrides the API logging option
and all API logging is redirected to the mid tier log file.
Data Visualization Module — Messages related to the data visualization module
Default value: All categories except Flashboards are selected by default.
arsystem.log_filesize Maximum size (in kilobytes) a BMC Remedy Mid Tier log file can reach before a backup
copy is automatically made. When the log file reaches this limit, a backup copy is made with
the same file name and an incremental number (for example, armidtierN.log).
Default value: 10240 KB
arsystem.log_format BMC Remedy Mid Tier log output, which is generated using the standard Java 1.5 logging
API, including Simple and XML formatting.
Valid values:
FastText — (Default) A basic text file for faster performance, it does not include stack
trace information except in the case of Severe log messages.
Text — A text file containing details such as JAVA class names and methods.
XML— A file in XML format.
arsystem.log_filepath Directory in which the BMC Remedy Mid Tier log files are stored. To change the log
directory, enter the absolute (complete) path for the new directory.
Note: You cannot change the log file name.

Default value: C:\Program Files\BMC Software\ARSystem\midtier\logs
arsystem.log_level log settings Level of detail for logging information for BMC Remedy Mid Tier.
Valid values:
Fine — The highest level of detail, including the client's IP address

Info — Less detail than Fine, but includes the client's IP address
Warning — A moderate level of detail. Warnings plus those errors included in the
Severe level are logged.
Severe — (Default) The lowest level of detail; only server start time and error
messages are logged
Note: You can see the pre-load start and end timestamp when you set the log level to Info or
Warning. Irrespective of the logging level, mid tier logs the pre-load start and end time.
arsystem.log_viewer log settings Method by which you want to view the BMC Remedy Mid Tier log files.
Valid values:
Console — The log entries are directed to the stderr (System.err) of your servlet
engine.
File — (Default) Data is saved to a file in the specified log directory.

Setting Description
arsystem.objectlist Flag that indicates whether the object list is enabled on BMC Remedy Mid Tier.
Valid values:
true (Default)
false
Note: When set to true, ensure that the corresponding form to display object the list is
imported on the AR System server.
arsystem.preference_servers_list Indication that preloading of the forms has been enabled for this AR System server.
Valid values:
true
false (Default)
arsystem. Maximum number of connections in the AR System server JavaAPI connection pooling.
pooling_max_connections_per_server Default value: 80
arsystem.session_timeout Number of minutes for which the current logon session remains inactive. When the time
exceeds the arsystem.session_timeout value without any activity in an application on the
BMC Remedy Mid Tier, you must log on again.
Default value: 90 minutes
arsystem.log_user User name for which statements are logged.

After you enter the user name and save changes, a new log file is started. For log messages
displayed on the screen, the filter applies only to new entries. Older entries that existed

Setting Description
before the user name was changed will still be displayed on the screen, up to the limit set in
the View Logs setting.
If the field is left blank, all logs related to the current session are stored, regardless of who is
logged in. You can enter only enter one name in this field.
ASJ-Thread-Count 2 (see page 1168) Specifies the total number of worker threads that process various approval requests.
approval)
Authentication-Chaining-Mode Mode that enables the administrator to use more than one type of authentication on the
same system.
Valid values:
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.
Auth-Token-Signature-Salt1 Name of a plugin used by the BMC Remedy AR System server to confirm the user password
information from the BMC Atrium Single Sign-On server.
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.
Configuration settings C-D


Note
Tip
box.
Setting list, or type the parameter name in the Setting text box.
Configuration settings (C-D)
Setting Description Sever group Maps to
configuration
Cache-Display-Properties 2 (see The way that the server caches form display No AR System
page 1200) properties. The form display property is the Configuration
background image of the form view and the display Generic UI
(Component name: com.bmc.arsys. property of each form field. form
server)
Valid values:
T — (Default) Cache all form-display properties.

F — Cache only server-display properties. (This
can negatively impact the performance of the
server if a form is changed, but it reduces the
amount
of memory used in the server cache.)

configuration
Cache-Mode The valid value for Cache-Mode is, No AR System

Administration
0 — (Default) Console >
System >
Note: You should always set the value for Cache-
General >
Mode to 0.
Server
Information >
Configuration
>
Development
Cache Mode.
(See Setting
administrative
options (see
page 291).)
Note: You
should not
change the
default value
for the
Development
Cache Mode
checkbox.
Cancel-Query-Option 2 (see page Flag indicating whether the cancel query functionality No AR System
1168) in a browser is enabled. Configuration
Generic UI
Valid values: form.
0 — Inactive
1 — (Default) Active
Changed-By-Another-Check Flag indicating whether the system checks whether No AR System

another user changed an entry after you retrieved the Configuration
entry. If you try to save modifications to an entry, you Generic UI
receive a warning and must confirm the save. form
Valid values:
T — (Default) Perform the check and issue a

warning.
F — Do not perform the check.
Client-Managed-Transaction- Maximum time (in seconds) to hold a transaction No AR System

Timeout before a timeout occurs. Administration
The default is 60 seconds, and there is no maximum. Console >
If a timeout occurs, the server automatically rolls the System >
transaction back, and the client receives an error on General >
the next operation that uses the transaction handle. Server
Information >
Advanced >
Transaction
Control

configuration
section >
Transaction
Timeout
(seconds).
(See Setting
performance
and security
options (see
page 285).)
Clustered-Index Flag indicating whether indexes for the database are No AR System
clustered. Configuration
Generic UI
Valid values: form
T — (Default) Use a clustered index.

F — Do not use a clustered index.
You must set this option before you start the

com.bmc.arsys.emaildaemon. Specifies the log level for email engine based on No AR System
level 2 (see page 1168) which the logs are generated in the email.log file Configuration
Generic UI
(Component name: com.bmc.arsys. Valid values: form
emaildaemon)
Off
Severe (Default)
Warning
Info
Config
Fine
Finer
Finest
Related functionality: Incoming and Outgoing
Related protocol: All Supported
com.bmc.arsys.emaildaemon. Specifies the log level for email engine based on No AR System
ARSystemHandler.level 2 (see which the logs are saved in the AR System Email Configuration
page 1168) Error Logs form Generic UI
form
emaildaemon)
Off (Default)
Severe
Warning
Info
Config
Fine
Finer
Finest

configuration
com.bmc.arsys.emaildaemon. Enables users to specify the log file path No AR System

logfileName Configuration
Note: Once the user specifies a file path, email engine Generic UI
(Component name: com.bmc.arsys. logs that user defined file only when it connects to AR form
emaildaemon) server. if any error occurred before connecting to
Centralized configuration form then logs will be stored
into default log file path.
Default value: emailEngineInstallDir/AREmail/Logs

/email.log
com.bmc.arsys.emaildaemon. Specifies the maximum size of the log file in bytes No AR System
logfilesize Configuration
If the file size exceeds this limit, a new file is created. Generic UI
(Component name: com.bmc.arsys. form
Default value: Unlimited
emaildaemon)
com.bmc.arsys.emaildaemon. Specifies additional email headers. Separate the No AR System

AdditionalMailHeaders 2 (see page additional email headers with commas. See Adding Configuration
1168) extra custom headers to outgoing SMTP emails (see Generic UI
page 1503). form
emaildaemon) Default value: X-Loop-Detect
Related functionality: Outgoing
Related protocol: SMTP
com.bmc.arsys.emaildaemon. Specifies the date and time format that the BMC No AR System
ARDATE 2 (see page 1168) Remedy Email Engine uses for parsing date and time Configuration
strings given in the incoming mails. MMMMM dd, Generic UI
(Component name: com.bmc.arsys. yyyy HH:mm:ss z is equivalent to December 21, form
emaildaemon) 2009 12:08:56 PDT.
Related functionality: Incoming
com.bmc.arsys.emaildaemon. Specifies the date format that BMC Remedy Email No AR System
ARDATEONLY 2 (see page 1168) Engine uses for parsing date strings given in incoming Configuration
mails. MMMMM dd, yyyy is equivalent to December Generic UI
(Component name: com.bmc.arsys. 21, 2009. form
emaildaemon)
Default value: X-Loop-Detect
com.bmc.arsys.emaildaemon. This setting lets you specify the time format used by No AR System
ARTIMEONLY 2 (see page 1168) BMC Remedy Email Engine Configuration
for parsing time strings given in incoming mails. HH: Generic UI
(Component name: com.bmc.arsys. mm:ss z is equivalent to 12:08:56 PDT. form
emaildaemon)
Default value: X-Loop-Detect

configuration
com.bmc.arsys.emaildaemon. This setting indicates whether to send the charset No AR System

ContentTypeWithCharset 2 (see property in the Content-Type header of an outgoing Configuration
page 1168) message. If you do not want the charset string to be Generic UI
present in the Content-Type header, set this property form
(Component name: com.bmc.arsys. to False.
emaildaemon)
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon. Specifies the number of entries to return when the No AR System

ChunkSize 2 (see page 1168) BMC Remedy Email Engine makes a call to the AR Configuration
System server. Generic UI
emaildaemon) Default value: 100
Note: The maximum value is also 100.
com.bmc.arsys.emaildaemon. Specifies whether you can use a comma as a No AR System

CommaValidAddressSeparator 2 separator when entering multiple addresses in the To Configuration
(see page 1168) and CC fields. If user names in the mail server contain Generic UI
commas, set this property to false (usually needed form
(Component name: com.bmc.arsys. only when using the MAPI protocol). For example, if
emaildaemon) names are stored on the mail server as:
Smith, John and
Cho, Rick
You would need to use semicolons to separate the
addresses:
Smith, John; Cho, Rick
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon. Specifies the amount of time in milliseconds for which No AR System

Exchange-Wait-Time 2 (see page the BMC Remedy Email Engine waits before Configuration
1168) processing the next incoming message, when there Generic UI
are more messages residing on the Exchange Server. form
emaildaemon) Default value: 1

configuration
com.bmc.arsys.emaildaemon. Specifies whether to fetch the user and group No AR System

FetchUserGroupInfoOnDemand 2 information about demand as opposed to loading all Configuration
(see page 1168) users and groups at startup. If there are many users or Generic UI
groups, you might want to set this property to true to form
(Component name: com.bmc.arsys. reduce the startup time for email.
emaildaemon)
Valid values:
True
False (Default)
com.bmc.arsys.emaildaemon. Determines whether the outgoing message header No AR System

getReplyToWithFromAddress 2 should contain the Reply To field and what its value Configuration
(see page 1168) should be.getReplyToWithFromAddress is not used Generic UI
by default. If you want the email engine to use this form
(Component name: com.bmc.arsys. property, you must add it to
emaildaemon) 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, and the value of this property
is:
false (or not provided) — The Reply To
field is not included in the outgoing
message header.
true — The Reply To field is included in
the outgoing message header, and its
value is the address in the From field of
the messages form.
If the Reply To Address field of the outgoing
mailbox configuration form or the Reply To field
of the messages form contains a value, the
message header will contain the Reply To
header value as set in the message, regardless
of value of this property.
Valid values:
True (Default)
False

configuration
com.bmc.arsys.emaildaemon. Specifies whether to wait before cancelling an attempt No AR System

IMAPTimeout to connect to the mail server and generating an error. Configuration
In case of an IMAP timeout, the email engine waits for Generic UI
(Component name: com.bmc.arsys. the timeout interval and then marks the queued form
emaildaemon) message as erroneous. IMAPTimeout 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.
Valid values:
True
False (Default)
Related protocol: IMAP
com.bmc.arsys.emaildaemon. Specifies the duration in number of seconds to wait No AR System

IMAPTimeoutPeriod before cancelling an attempt to connect to the mail Configuration
server and generating an error. In case of an IMAP Generic UI
(Component name: com.bmc.arsys. timeout, the email engine waits for this interval and form
emaildaemon) then marks the queued message as an erroneous.
IMAPTimeoutPeriod 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.
Related protocol: IMAP
com.bmc.arsys.emaildaemon. Specifies the default number of email messages the No AR System

IncomingConnectionRecycleSize email engine receives before the connection is closed Configuration
2 (see page 1168) and reopened. In the 5.1 and 5.1.1 releases of the Generic UI
email engine, the connection with the mail server was form
(Component name: com.bmc.arsys. closed only after reading all incoming messages.
emaildaemon) Consequently, if the email engine crashed or hung
before the connection was closed, it was possible that
messages marked for deletion would not be deleted
from the mail server. This property helps you avoid
that situation.
Default value: 100
com.bmc.arsys.emaildaemon. Specifies the message queue size (number of emails). No AR System

IncomingMessagesQueueSize 2 The Receiver module Configuration
(see page 1168) writes messages to the queue, and the Execution Generic UI
module reads messages from this queue to parse and form
(Component name: com.bmc.arsys. execute. The Receiver module still writes messages to
emaildaemon) the server in AR System Email Messages form, but

configuration
the Execution module reads the message from the

message queue instead of from the server. This
reduces the traffic to the AR System server and
improves the performance.
Default value: 100
com.bmc.arsys.emaildaemon. Specifies the number of instructions to be stored in the No AR System

instructionCacheSize 2 (see page cache, which is used to improve performance. If the Configuration
1168) value of this property is set to 15, the cache already Generic UI
contains 15 instructions, and another instruction is to form
(Component name: com.bmc.arsys. be added, then the oldest instruction is removed to
emaildaemon) 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
Default value: 20
com.bmc.arsys.emaildaemon. If you run multiple instances of the email engine on a No AR System

Mailboxes 2 (see page 1168) single server, this property specifies which mailboxes Configuration
should the email engine process. The value of this Generic UI
(Component name: com.bmc.arsys. property should contain comma-separated mailbox form
emaildaemon) 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. Specifies whether the polling interval is to be No AR System

MailboxPollingUnitIsMinutes 2 considered in minutes (as configured in AR System Configuration
(see page 1168) Email Mailbox Configuration form) or seconds. The Generic UI
email engine interprets the value of this property as form
(Component name: com.bmc.arsys. follows:
emaildaemon)
true — Consider the polling interval in minutes.
false — Consider the polling interval in
seconds.
Note: Whatever measure of unit you select applies to

all configured mailboxes that are enabled.
Valid values:
True (Default)

configuration
False
com.bmc.arsys.emaildaemon. Specifies the attachment types that you want to permit No AR System
MaxAttachSize and com.bmc. in an email message and the maximum size of each Configuration
arsys. emaildaemon. attachment. MaxAttachSize specifies the maximum Generic UI
MaxAttachSizeFileExtensions 2 size limit for attachments, whereas form
(see page 1168) MaxAttachSizeFileExtensions specifies the file types
by
(Component name: com.bmc.arsys. using comma-separated extensions. These properties
emaildaemon) must be used together to impose limits on email
attachments of specific file types. For example, to set
the maximum size of .doc, .pdf, and .xls attachments
to 1000000 bytes (1 MB), use the following syntax:
com.bmc.arsys.emaildaemon.
MaxAttachSize=1000000 com.bmc.arsys.
emaildaemon. MaxAttachSizeFileExtensions=doc,
pdf,xls The size limit is not imposed on files whose
extensions are not specified by using
MaxAttachSizeFileExtensions. Email messages with
attachments that exceed this limit are logged to the
AR System Email Error Logs form. Optionally, you can
create workflow for this form to process such
messages separately.
Valid values:
True
False (Default)
com.bmc.arsys.emaildaemon. The email engine interprets the value of this property No AR System
MBOXFromLineWith-At-The- as follows: Configuration
Rate-Sign 2 (see page 1168) Generic UI
true — BMC Remedy Email Engine fetches form
(Component name: com.bmc.arsys. only those messages that contain the @ sign in
emaildaemon) the "from line" (from address).
false — BMC Remedy Email Engine fetches all
the messages.
Valid values:
True
False (Default)
Related protocol: MBOX
com.bmc.arsys.emaildaemon. Specifies the interval in minutes between checks to No

Monitor 2 (see page 1168) see if all the threads are functioning properly.

configuration
(Component name: com.bmc.arsys. Note: If the monitoring system detects that a thread AR System
emaildaemon) has failed, it restarts the thread. Configuration
Generic UI
Default value: 30 minutes form
com.bmc.arsys.emaildaemon. Specifies the number of sender threads that the email No AR System
NumberOfSenderThreads 2 (see daemon uses for each outgoing mailbox. The optimum Configuration
page 1168) number of threads depends on many factors including Generic UI
the number of mailboxes, the hardware configuration, form
(Component name: com.bmc.arsys. and so on.
emaildaemon)
Valid values: 1 through 20
Default value: 4

POP3Timeout to connect to the mail server and generating an error. Configuration
In case of an POP3 timeout, the email engine waits for Generic UI
(Component name: com.bmc.arsys. the timeout interval and then marks the queued form
emaildaemon)
message as erroneous. POP3Timeout is not used by
and set its value to true. When you set POP3Timeout
to true, the POP3TimeoutPeriod property is used.
Valid values:
True
False (Default)
Related protocol: POP3

POP3TimeoutPeriod before cancelling an attempt to connect to the mail Configuration
server and generating an error. In case of an POP3 Generic UI
(Component name: com.bmc.arsys. timeout, the email engine waits for this interval and form
emaildaemon) then marks the queued message as an erroneous.
POP3TimeoutPeriod is not used by default. If you
add it to EmailDaemon.properties and set its value to
any positive integer.
Related protocol: POP3
com.bmc.arsys.emaildaemon. No
SaveSentItem 2 (see page 1168)

configuration
(Component name: com.bmc.arsys. Specifies whether to retain messages in the Email AR System
emaildaemon) Messages form after sending. To delete sent Configuration
messages from the Email Messages form, set this Generic UI
property to False. form
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon. Specifies the number of security keys to be stored in No AR System

securityCacheSize 2 (see page 1168) the cache. If the value of this property is set to 15, the Configuration
cache already contains 15 security keys, and another Generic UI
(Component name: com.bmc.arsys. key is to be added, then the oldest key is removed to form
emaildaemon) accommodate the newest one.

AR System Email Security form, the security cache is
flushed based on the setting of the serverName.
Interval property.
Default value: 20
com.bmc.arsys.emaildaemon. Specifies the number of outgoing emails to query at a No AR System

SendEmailSetSize 2 (see page 1168) time. Configuration
Generic UI
(Component name: com.bmc.arsys. Default value: 100 form
emaildaemon)

SMTPTimeout 2 (see page 1168) to connect to the mail server and generating an error. Configuration
In case of an SMTP timeout, the email engine waits Generic UI
(Component name: com.bmc.arsys. for the timeout interval and then marks the queued form
emaildaemon) message as erroneous.SMTPTimeout is not used by
and set its value to true. If you add the property but do
not specify a value, it is considered as false.
Valid values:
True
False (Default)

configuration

SMTPTimeoutPeriod 2 (see page before cancelling an attempt to connect to the mail Configuration
1168) server and generating an error. In case of an SMTP Generic UI
timeout, the email engine waits for this interval and form
(Component name: com.bmc.arsys. then marks the queued message as an erroneous.
emaildaemon) SMTPTimeoutPeriod is not used by default. If you
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.
com.bmc.arsys.emaildaemon. Specifies whether to process messages with a higher No AR System

SortMessages 2 (see page 1168) priority setting first. Configuration
Generic UI
(Component name: com.bmc.arsys. Valid values: form
emaildaemon)
True
False (Default)
com.bmc.arsys.emaildaemon. Specifies whether to store instructions and instruction No AR System

StoreInstructions 2 (see page 1168) parameters in the AR System server. If set to true, the Configuration
email engine retains data in the Email Instructions and Generic UI
(Component name: com.bmc.arsys. Instruction Parameters forms for troubleshooting. form
emaildaemon) Then, you must delete this data explicitly. The
Execution module in the BMC Remedy Email Engine
handles both the parsing and execution of messages.
There will be one message queue created for each
Incoming mailbox. By default, instructions are not
stored in the server.
Valid values:
True
False (Default)
com.bmc.arsys.emaildaemon. This property is not available by default. No AR System

SynchronizedLoggingMode 2 (see Configuration
page 1168) Valid values: Generic UI
form

configuration
True — The synchronized logging mode is

used.
emaildaemon) False (Default) — The bulk API 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. Specifies the number of email templates to be stored No AR System

templateCacheSize 2 (see page 1168) in the cache to improve the performance. If the value Configuration
of this property is set to 15, Generic UI
(Component name: com.bmc.arsys. the cache already contains 15 templates, and another form
emaildaemon) template is to be added, then the oldest template is
removed to accommodate the newest one.

AR System Email Templates form, the templates
cache is flushed based on the setting of the
Default value: 20
com.bmc.arsys.emaildaemon. Specifies whether an <a href> tag is placed around a No AR System

URLWithHrefTag 2 (see page 1168) URL in an HTML message. If the setting is true, the Configuration
<a href> tag is used. If the setting is false, the URL is Generic UI
(Component name: com.bmc.arsys. not enclosed in an <a href> tag. form
emaildaemon)
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon. Specifies whether to retain display names that do not No AR System

UseNameIfNoEmailAddress 2 (see have email addresses associated with them in the To, Configuration
page 1168) CC, or BCC fields. If the setting is true, the display Generic UI
names are not removed from the To, CC, or BCC form
(Component name: com.bmc.arsys. fields. If the setting is false, the display names are
emaildaemon) 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.

configuration
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon. Specifies the number of users (records from the User No AR System
UserChunkSize 2 (see page 1168) form) to retrieve Configuration
from the AR System server at one time. This setting Generic UI
(Component name: com.bmc.arsys. can be used to tune the form
emaildaemon) email engine's performance.
Default value: 5000
com.bmc.arsys.emaildaemon. Specifies the email address of the administrator. If a No AR System

AdminAddresses 2 (see page 1168) database transaction fails while storing an incoming Configuration
message, the email engine forwards the original mail Generic UI
(Component name: com.bmc.arsys. to this email address, so that it is retained. An form
emaildaemon) example of a transaction failure could be when the
database is full and cannot save anymore incoming
email messages. You can specify multiple addresses
separated by commas.
Note: This property can be used only when the BMC

Remedy Email Engine does not capture the error out
incoming email messages in the BMC Remedy AR
System Email Error Messages Form.
Default value: Default value is set to the administrator

address specified during installation.
ConfigFileCheckInterval Interval (in seconds) after which the BMC Remedy No AR System
Flashboard server checks for the changes to the Administration
(Component name: com.bmc.arsys. server.conf file. Console >
flashboardServer )
System >
Default value: 60 seconds General >
Flashboard
Server
Configuration
> Config File
Check Interval
.
(See AR
System
Administration -
Flashboard

configuration
Server
Configuration
(see page 645)
.)
Configuration-Name 2 (see page 1168 Name of the component. No AR System

) Configuration
AR System server uses this option to identify the
Generic UI
(Component name: com.bmc.arsys. active component in the database. form
server)
Create-Entry-DeadLock-Retries 2 Number of times to retry the ARCreateEntry() No AR System

(see page 1168) function during deadlock situations. Value is an Configuration
integer. Generic UI
form
Create-Entry-DeadLock-Retries- Delay, in seconds, between each retry of a No AR System

Delay 2 (see page 1168) deadlocked ARCreateEntry() function. Value is an Configuration
integer. Generic UI
form
Crossref-Blank-Password Flag indicating how the system responds when a No AR System

user's logon name is not assigned a password in the Configuration
User form. Generic UI
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- Number of minutes between each refresh of currency No AR System

Interval 2 (see page 1168) conversion ratios on the client. Configuration
Generic UI
server)
Db-Case-Insensitive 1 (see page 1200 Flag indicating whether to perform case-insensitive No AR System
) queries on Run If qualifications for active links, filters, Configuration
and escalations. (For Oracle databases, ensure that Generic UI
this option matches the behavior of your Oracle form
database so that all queries are consistent.)
Valid values:

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

configuration
The Oracle client is at least version 11.2.

The database administrator sets cursor sharing
to EXACT for the functional indexes that Oracle
Optimizer will use (otherwise, performance can
be severely degraded due to full table scans).
Note: Depending on the volume of data, creating

functional indexes may take a long time.
Db-Character-Set 2 (see page 1168) Option that initializes an internal variable that the No AR System
server uses for various purposes, such as informing Configuration
(Component name: com.bmc.arsys. the ARGetServerInfo function's Generic UI
server) AR_SERVER_INFO_DB_CHAR_SET server option form
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 (see page Number of times the BMC Remedy AR System server No AR System
1168) tries to reestablish a lost connection to the database. Configuration
The default is 100. The server retries the connection Generic UI
once every 15 seconds up to the specified number of form
times. For example, when this option is set to 100, the
server retries the connection once every 15 seconds
for a duration of 25 minutes.
Db-Host-Name 2 (see page 1168) Logical server name of the underlying database. No AR System
Configuration
(Component name: com.bmc.arsys. Generic UI
server) form
Db-Max-Attach-Size 2 (see page 1168) Maximum size (in bytes) of compressed attachments No AR System
that the AR System server can retrieve from Oracle Configuration
databases. The default value is 2 GB. This value is Generic UI
limited by your server operating system and form
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 No AR System

size for long character text data in databases. For Configuration
2 (see page 1168)
Oracle databases, this value is also used for memory Generic UI
allocation during the processing of long text data; form
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.

configuration
Db-name 1 (see page 1200) For Oracle, the name of the tablespace that the AR No AR System
System server uses. For all other supported Configuration
(Component name: com.bmc.arsys. databases, the name of the underlying SQL database. Generic UI
server) The default value is ARSystem. form
Db-password (DB2, Microsoft SQL Server, Oracle, and Sybase) No AR System

Database password associated with the ARSystem Configuration
(Component name: com.bmc.arsys. database and table space. The password can be Generic UI
server) form
modified by using the ARSetServerInfo function and
is stored in encrypted form. If you change the
password manually, specify this option by using clear
text, and change the password by using the AR
System Administration: Server Information form to
encrypt it.
Db-Type 1 (see page 1200) The type of database the AR System server is No AR System
connecting to. Configuration
server) Valid values: form
DB2
Microsoft SQL Server
Oracle
Sybase
Mysql
Db-user 1 (see page 1200) (Microsoft SQL Server, Oracle, and Sybase) User No AR System
name that AR System uses to access the underlying Configuration
(Component name: com.bmc.arsys. database. The default is ARAdmin. Generic UI
server) form
DB2-Database-Alias DB2 database alias name for the AR System No AR System

database. Configuration
Generic UI
form
DB2-Server-Name DB2 database server name. No AR System

Configuration
Generic UI
form
Debug-GroupId Name of the group to which a user must belong to use No AR System
logging options such as API, database, and filter Configuration
logging in BMC Remedy AR System clients. Logging Generic UI
options are disabled for users who are not members of form
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 No AR System

activate one bit, set this option to its value (see the Configuration
(Component name: com.bmc.arsys. following list). To activate two or more bits, add their Generic UI
server) values, and set this option to the total. For example, to form
activate bits 1 and 3, set this option to 5 because bit 1

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

configuration
Default-Allowable-Currencies Default allowable currency types for currency fields in No AR System

clients. Configuration
Generic UI
form
Default-Functional-Currencies Default functional currency types for currency fields in No AR System

clients. Configuration
Generic UI
form
Default-messaging-port Specifies port for JMS (Java Messaging Service) used No System >
by Java server for asynchronous communication General >
within server or server group. Server
Information >
Default value: 61617 Ports and
Queues >
Message
Broker Port.
(See Setting
ports and RPC
numbers (see
page 274).)
Default-Order-By 2 (see page 1168) Flag indicating whether to apply the default sort order No AR System
to search results. Configuration
Generic UI
Valid values: form
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 No AR System
pointing to the BMC Remedy AR System server. Administration
Console >
System >
General >
Server
Information >
Advanced >
Default Web
Path.
(See Setting
performance
and security
options (see
page 285).)
Delay-Recache-Time No AR System
Administration
2 (see page 1168)
Console >
System >

configuration
Number of seconds before the latest cache is made General >

available to all threads. Valid values: 0 to 3600 Server
seconds. If this option is set to 0, every API call gets Information >
the latest cache (that is, the cache is copied for every Configuration
administrator call). Setting the option to 0 causes > Recache
slower performance for cache operations. Delay.
Default value: 5 seconds (See Setting

administrative
options (see
page 291).)
Dev-Studio-Development-Mode Indicates whether you can use BMC Remedy No AR System

Developer Studio in the Best Practice Mode, Base Configuration
Mode or both. Generic UI
form
Valid values:
1 — Allows you to work in the Base Mode
2 — (Default) Allows you to work in the Best Practice

mode
3 — Enable both the modes
Disable-Admin-Ops Flag indicating whether administrative operations are No AR System

allowed on the server. Administration
Console >
Valid values: System >
General >
F — Enabled (Default)
Server
T — Disabled
Information >
If the Server Groups check box is selected, this option Configuration
is ignored. > Disable
Server groups can be configured in the BMC Remedy Admin
AR System Server Group Operation Ranking form to Operations.
make sure that only one server performs the
(See Setting
operation. See Configuring server groups (see page
administrative
342).
options (see
page 291).)
Disable-Admin-Ops-Global Flag indicating whether administrative operations are Yes AR System

allowed on all the servers. Configuration
Generic UI
Valid values: form
F — Enabled (Default)
T — Disabled
In a server group environment:
This configuration setting is shared among all

the servers.
If you set this parameter on any of the servers,
it will be applicable for all the servers.

configuration
For non-server group environment, this parameter is

same as Disable-Admin-Ops. If you configure this
parameter, Disable-Admin-Ops is automatically
updated with the same value.
You can set the parameter value from the AR System

using the following steps:
1. Open AR System administration console.

2. Click System > General > Centralized
Configuration.
3. Select com.bmc.arsys.server.shared >
shared. The list of already added shared
parameters appears.
4. Add new parameter with name Disable-Admin-
Ops-Global and set the value as F or T to
enable or disable admin operations.
Note: You can also update the parameter using these

steps, if it already exists.
Disable-Alerts Flag indicating whether alerts are sent when alert No AR System
events are created. Administration
Console >
Valid values: System >
General >
T — No threads are started in the alert queue,
Server
and no alerts are sent.
Information >
F — (Default) Alerts are enabled.
Configuration
> Disable
Changes to this setting do not take effect until
Alerts.
the server is restarted.
(See Setting
administrative
options (see
page 291).)
Disable-Archive Switch that disables (T ) or enables (F ) the archive No AR System

when the server starts. Administration
2 (see page 1168)
Console >
System >
General >
Server
Information >
Configuration
> Disable
Archive. (See
Setting
administrative
options (see
page 291).)
Disable-Archive-Global Switch that disables (T ) or enables (F - default) the Yes

archive when the server starts.

configuration
In a server group environment: AR System

Configuration
This configuration setting is shared among all Generic UI
the servers. form

same as Disable-Archive. If you configure this
parameter, Disable-Archive is automatically updated
with the same value.

using the following steps:

Configuration.
parameters appears.
4. Add the parameter with name Disable-Archive-
Global and set the value as F or T to enable or
disable archive operations.

Disable-ARSignals Flag indicating whether automatic signals triggered by No AR System

changes to the following data on a server group's Administration
2 (see page 1168)
administrative server are disabled: Console >
System >
Archive definitions General >
Escalation definitions Server
Group information from the database Information >
Configuration
The signals can be generated by arsignald or > Disable
the database. Signals triggered by changes to ARSignals.
user, licensing, and computed group (See Setting
information are not disabled. administrative
options (see
Valid values:
page 291).)
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 page 1141)). See Signaling mechanism in a
server group (see page 347).
Disable-Audit-Only-Changed- No
Fields

configuration
(Component name: com.bmc.arsys. Flag indicating whether to audit all records (T ), or to AR System
server) audit only those records whose field values have Administration
changed (F, the default). Console >
System >
General >
Server
Information >
Configuration
> Disable
Audit Only
Changed
Fields.
(See Setting
administrative
options (see
page 291).)
Disable-Client-Operation Option that restricts time-consuming operations (such No AR System

as reporting) during busy times, improving overall Configuration
2 (see page 1168)
performance. The syntax is Generic UI
form
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-

configuration
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 Switch that disables (T ) or enables (F - default) the No AR System

escalations when the server starts. If the Server Group Administration
Member check box is selected, this option is ignored. Console >
Server groups can be configured in the BMC Remedy System >
AR System Server Group Operation Ranking form to General >
make sure that only one server performs the Server
operation. See Configuring server groups (see page Information >
342). Configuration
> Disable
Escalations.
(See Setting
administrative
options (see
page 291).)
Disable-Escalations-Global Switch that disables (T ) or enables (F - default) the Yes AR System

escalations when the server starts. Configuration
Generic UI
In a server group environment: form

configuration
This configuration setting is shared among all

the servers.

same as Disable-Escalations. If you configure this
parameter, Disable-Escalations is automatically
updated with the same value.

Administration Console using the following steps:

Configuration.
parameters appears.
4. Add new parameter with name Disable-
Escalations-Global and set the value as F or T
to enable or disable escalations.

Disable-Non-Unicode-Clients Flag indicating whether Unicode servers can refuse No AR System

requests from Administration
non-Unicode clients (for example, not Mid Tier 7.0.00). Console >
This option does not affect non-Unicode servers. System >
General >
Valid values: Server
Information >
T — Unicode servers refuse requests from non-
Configuration
Unicode clients.
> Disallow Non
F — (Default) Unicode and non-Unicode clients
.
can contact Unicode servers.
(See Setting
administrative
options (see
page 291).)
Disable-User-Cache-Utilities Flag that prevents unauthorized users from using User No AR System
Cache commands. Configuration
Generic UI
Valid values: form
T — The *arreload* and arcache utilities are

disabled for the AR System server.
F — (Default) Cache utilities are enabled.
Dispatch-Log-File Flag that indicates whether the dispatcher logging is No AR System

enabled. Configuration
Generic UI
Valid values: form

configuration
T — The dispatcher logging is enabled. When

you enable the dispatcher logging, specify the
log filename that you want to use.
F — (Default) The dispatcher logging is
disabled.
Display-General-Auth-Message 2 Flag indicating whether to display a message when No AR System

(see page 1168) user authentication fails. Configuration
Generic UI
Valid values: form
T— (Default) A generic message is displayed

for user name and password errors:
ARERR 623 Authentication
failed
ARERR9388Authentication failed
F— Each authentication error displays a
different message:
ARERR 624 User account locked
out due to too many bad
password attempts
ARERR9381 No such user is
registered with this server
ARERR9382Invalid password or
authentication string for
existing user
This parameter can be used in conjunction with Max-

Password-Attempts. See Configuration settings E-M
(see page 1201).
Distrib-Log-File Full path name of the file to use if DSO server logging No AR System
is on (see Debug-mode (see page 1186)). Configuration
Generic UI
form
Domain-Name 2 (see page 1168) New domain name portion of the fully qualified server No AR System
name. By default, a server determines the domain Configuration
name from the network interface. In rare cases, this Generic UI
method does not produce the desired result because form
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 No AR System

operations: Administration
(Component name: com.bmc.arsys. Console >
server) DSO checks for changes to the source and System >
target forms General >
Updates of cached DSO mapping information Server
Information >
By default, this option is set to 1800 seconds DSO > Cache
(30 minutes). The maximum value is 43200 Check Interval
seconds (12 hours). .

configuration
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Error-Retry-Option DSO server retry behavior after an error: No AR System

Administration
(Component name: com.bmc.arsys. 0 — (Default) Retry after standard connection Console >
server) and transmission errors. System >
1 — Never retry after any error. General >
2 — Retry after every error. Server
3 — Retry after standard connection and Information >
transmission errors and after database errors. DSO > Error
Retry Option.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Host-Name 2 Name to use for the From (source) server in No AR System

distributed mappings. This setting enables you to use Configuration
(Component name: com.bmc.arsys. an alias for the From server in distributed operations. Generic UI
server) form
DSO-Local-RPC-Socket RPC program number that DSO uses. This setting is No AR System
optional. Administration
(Component name: com.bmc.arsys. Console >
server) System >
General >
Server
Information >
DSO > DSO
Local RPC
Program
Number.
(See Setting
server
passwords,
RPC options,
and plug-in
timeouts (see
page 288).)
DSO-Log-Level No

configuration
Level of logging for all DSO logs (ardist.log, ardist. AR System

log.default, ardist. poolName.log, and ardist.log. Configuration
server) Generic UI
poolName ):
form
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 No AR System
Java log file. If you do not specify a value for this Configuration
(Component name: com.bmc.arsys. option, 5 indexed backups are saved for each DSO Generic UI
server) Java log file. form
DSO-Main-Thread-Polling- Interval at which the DSO server queries the No AR System

Interval distributed pending queue for pending distributed Administration
items. Enter any integer from 0 (no polling) to 3600 Console >
(Component name: com.bmc.arsys. seconds (1 hour). System >
server) General >
Server
Information >
DSO > Polling
Interval.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Mark-Pending-Retry-Flag Flag indicating whether to set the status of items in the No AR System
DSO distributed pending queue to Retry after an Administration
(Component name: com.bmc.arsys. attempt to perform the associated operation fails. Console >
server) (Failure must be due to a recoverable error. Items that System >
fail because of nonrecoverable errors are removed General >
from the queue.) Server
Information >
Valid values: DSO > Mark
Pending Retry
T — (Default) Does not set the status to Retry.
.
Instead, the status remains set to New.
Depending on the number of pending items that (See AR
the DSO server processes, this setting might System
improve the server's performance. Administration -
F — Sets the status to Retry. Use this to Server
differentiate items in the queue that have never Information
been processed (status = New) from items that form - DSO tab
were processed but failed because of (see page 544)
recoverable errors (status = Retry). .)

configuration
Note: Regardless of this option's value, the

pending item is retried based on its retry
configuration.
DSO-Max-Pending-Records-Per- Maximum number of records in the Distributed No AR System

Query Pending form that DSO reads in a single database Administration
query. Minimum value is 1. Maximum value is Console >
(Component name: com.bmc.arsys. unlimited. System >
server) General >
Default: 1000
Server
Information >
DSO > Max
Pending
Records Per
Query.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Merge-DupID-Overwrite 2 The way the DSO server behaves when it finds a No AR System
(see page 1168) duplicate request ID on the target server. Valid Configuration
values: Generic UI
server) 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 No AR System
same host as the AR System server. Use this when Administration
(Component name: com.bmc.arsys. setting up a DSO server outside a firewall to support Console >
server) an AR System server running behind a firewall. Server
Information
form > DSO
tab >
Placeholder
Mode.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)

configuration
DSO-Polling-Interval Interval (in seconds) at which the DSO server checks No AR System
the distributed pending queue for pending distributed Administration
(Component name: com.bmc.arsys. items. This is used as a backup when no signals are Console >
server) received from workflow. The value can be any integer System >
between 15 and 7200. By default, the backup General >
polling interval is disabled. Server
Information >
DSO > Polling
Interval.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Source-Server The AR System server for a DSO server to support No AR System

when that AR System server is different from the one Administration
(Component name: com.bmc.arsys. installed with the DSO server. Use this when setting Console >
server) up a DSO server outside a firewall to support an AR System >
System server running behind a firewall. Note: Use General >
this entry to configure DSO for load balancing. Server
Information >
DSO > Source
Server.
(See AR
System
Administration -
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Supress-No-Such-Entry- Flag indicating whether to log AR System server error No AR System

For-Delete 302 (entry does not exist in database) in the arerror. Administration
log file when performing distributed delete operations. Console >
(Component name: com.bmc.arsys. System >
server) Valid values: General >
Server
T — Do not log ARERR 302 during distributed
Information >
deletes.
DSO >
F — (Default) Log ARERR 302 during
Suppress No
distributed deletes except when the DSO-Error-
Such Entry
Retry-Option is set to 2 (retry after every error).
Error for
Distributed
Note: When this option is set to T, errors
Delete.
caused by valid problems might also be omitted
from the log. (See AR
System
Administration -

configuration
Server
Information
form - DSO tab
(see page 544)
.)
DSO-Target-Connection Information for the target BMC Remedy AR System No AR System

server. Use this format:DSO-Target-Connection: Administration
(Component name: com.bmc.arsys. serverName:RPCNumber portNumber Console >
server) System >
General >
Server
Information >
Connection
Settings >
DSO Server >
Target
connection
settings tables
.
(See Setting
server
passwords,
RPC options,
and plug-in
timeouts.)
DSO-Target-Password Password used to access the target BMC Remedy AR No AR System

System server through the DSO server. Use this Configuration
(Component name: com.bmc.arsys. format:DSO-Target-Password: serverName: Generic UI
server) encryptedPassword form
DSO-Timeout-Normal Timeout (in seconds) that the DSO server applies No AR System
during communication with the AR System server. Configuration
Enter an integer between 60 (1 minute) and 21600 (6
server) form
hours). If no value is specified, the system uses the
default timeout (120 seconds).
DSO-User-Password Password for the local DSO server user. No AR System

Configuration
server) form

Configuration settings E-M

Note
Tip
box. For example, to search for the Next-ID-Block-Size parameter, select it from
the Setting list, or type the parameter name in the Setting text box.
type the string in the Description text box. For example, to search for the
parameters which have Configuration in the description, type Configuration in
the Description text box.
Configuration options (E-M)
Setting Description Server group Maps to

configuration
Email-Notify-From Sender name to use for filter-generated email notifications in which No AR System
2 (see page 1216) no subject is specified. The value is limited to 29 characters. Configuration
Generic UI
form
Email-Timeout 2 No
(see page 1216)


configuration
Maximum time that arserverd waits for a return value from sendmail. AR System
This option was valid in AR System versions 4.5.1 through 5.0.1 but Configuration
became obsolete when the Email Engine was introduced in version Generic UI
5.1.0. form
Enable-Unlimited- Flag indicating whether log files display complete lines into log files or No AR System
Log-Line-Length not. Values are: Configuration
Generic UI
T — AR System server logs complete lines into log files form
without truncation.
F — (Default) AR System server logs only 255 characters per
line.
Encrypt-Data- Integer indicating the encryption algorithm of the data key. Use the No AR System
Encryption- following values.Standard Security Configuration
Algorithm Generic UI
1 — 56-bit DES using CBC mode (default) form
Performance Security
Premium Security

Encrypt-Public- Integer indicating the encryption algorithm of the public key. Values No AR System
Key-Algorithm are Configuration
Generic UI
4 — 512-bit RSA key (default for Standard Security) form
5 — 1024-bit RSA key (default for Performance Security)
6 — 2048-bit RSA key (default for Premium Security)
Encrypt-Public- Integer specifying the life span (in seconds) of the public key. At the No AR System
Key-Expire end of the specified time, the key expires, and the server generates a Configuration
new key. The default is 86400 seconds (24 hours). Generic UI
form
Encrypt-Security- Integer indicating whether encryption is on or off. Values are No AR System

Policy Configuration
0 — (Default) Optional: Clients with and without encryption Generic UI
installed can communicate with the server. Network traffic is form
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.


configuration
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- Size of the hash table that holds the encrypted session information. No AR System
Hash-Entries 2 (see The default is 509; there is no maximum. Configuration
page 1216) Generic UI
form
Encrypt- Integer specifying the life span (in seconds) of the data key. At the No AR System
Symmetric-Data- end of the specified time, the key expires, and a new key exchange Configuration
Key-Expire occurs. The default is 2700 seconds (45 minutes). Generic UI
form
Errors-Triggering- The error codes separated by semicolon, which will automatically Yes AR System
AlwaysOnLog- dump the Always On Logging buffer, if the specified error codes occur Administration
Dump during the execution. Console >
System >
General >
Server
Information >
Always On
Logging >
Errors
Triggering Log
. (See Setting
Always On
logging (see
page 339).)
Escalation-Log-File Full path name of the file to use if escalation logging is on (see Debug- No AR System
mode (see page 1186)). Configuration
Generic UI
form
Exception- Integer value controlling the diagnostic output when the server No AR System
Diagnostic-Option crashes. Values are Configuration
2 (see page 1216) Generic UI
0 — AR_EXCEPTION_DIAG_ALL ; includes all diagnostic form
output when an exception occurs.
1 — AR_EXCEPTION_EXCLUDE_STACK ; excludes the
stack trace in the diagnostic output when an exception occurs.
External- Mapping of LDAP groups to BMC Remedy AR System groups for No AR System
Authentication- external authentication. The value of this option consists of one or Configuration
Group-Mapping 2 more pairs of group names separated by semicolons. For example: Generic UI
(see page 1216) "LDAP-1" "ARS-1";"LDAP-2" "ARS-2";"LDAP-3" "ARS-3" Use form
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


configuration
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- Flag used by AR System during external authentication. Values are No AR System
Authentication- Configuration
Ignore-Excess- 0 — (Default) Users are authenticated when a match exists Generic UI
Groups 2 (see page between every LDAP group to which a user belongs and a form
1216) 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- Bit mask that specifies the return data capabilities for the current No AR System
Authentication- AREA plug-in. This option does not control the AREA plug-in; it Configuration
Return-Data- merely describes the behavior of the plug-in, enabling server Generic UI
Capabilities 2 (see optimization. Values are form
page 1216)
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- RPC socket number on which an external authentication server No AR System

Authentication- awaits requests for authentication. The default value is 0 (external Configuration
RPC-Socket authentication is not used). The RPC program number for the plug-in Generic UI
server is 390695. form
External- RPC timeout (in seconds) used when calling the authentication No AR System
Authentication- (AREA) server. The default value is 40 seconds. Configuration
RPC-Timeout Generic UI
form
External- Internal timeout (in seconds) that the BMC Remedy AR System No AR System
Authentication- server uses to invoke the external authentication server's Configuration
Sync-Timeout AREANeedToSyncCallback() function periodically. This function Generic UI
instructs the BMC Remedy AR System server to renew its internally form
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.


configuration
Filter-Api-Timeout Time limit (in seconds) for the Filter API RPC to respond to the No AR System
server's request before an error is returned. The minimum value is 1. Configuration
The maximum is 300. The default is 40. Generic UI
form
Filter-Log-File Full path name of the file to use if filter logging is on (see Debug-mode No AR System
(see page 1186)). Configuration
Generic UI
form
Filter-Max-Stack Maximum number of recursion levels allowed for an operation. The No AR System
data modification performed by an AR_FILTER_ACTION_FIELDP Configuration
filter action might trigger a second set, or level, of filters, one of which Generic UI
might trigger a third level of filters and so on. This option limits the form
number of times such recursion can happen, preventing the server
crash that would occur if the recursion continued indefinitely. The
Filter-Max-Total Maximum number of filters that the server executes for a given No AR System
operation. The default value is 10000. Configuration
Generic UI
form
Flush-Log-Lines Flag indicating whether logged lines are buffered or written directly to No AR System
disc. Values are: Configuration
Generic UI
T — (Default) Logged lines are written to disc. form
F — Logged lines are buffered.
Full-Text-Case- Flag indicating whether full text searching is case sensitive or case No AR System
Option insensitive. This setting affects all fields indexed for full text search Configuration
and affects how the indexes are built. Therefore, changes to this Generic UI
setting trigger an automatic re-index. Values are form
0 — Full text search is case sensitive

1 — (Default) Full text search is case insensitive
Full-Text- Location in the file system where search engine index files are stored. No AR System
Collection- Configuration
Directory 1 (see Generic UI
page 1216) form
(Component name:
com.bmc.arsys.
server)
Full-Text- Location in the file system where search engine configuration files are No AR System
Configuration- stored. Configuration
Directory Generic UI
Note: If you change the directory in this option, update the form
(Component name: pluginsvr_config.xml file with the correct directory path. This file is
com.bmc.arsys. in ARSystemInstallDir\pluginsvr\fts.
server)
Full-Text-Disable- Flag indicating whether the server processes pending indexing tasks. No
Indexing Values are


configuration
T — Disable indexing. Pending indexing tasks are recorded for AR System

processing later when indexing is enabled. Configuration
F — (Default) Do not disable indexing. Generic UI
form
Full-Text-Disable- Flag indicating whether the server uses the full text search engine for No AR System
Searching searching. Values are Configuration
Generic UI
T — Disable the full text search engine. The server uses the form
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- Full path name of the file to use if full text indexer logging is on (see No AR System
Log-File Debug-mode (see page 1186)). Configuration
Generic UI
form
Full-Text-Indexer- Number of minutes that the server waits between periodic attempts to No AR System
Recovery-Interval index entries that failed to index for an unexpected reason in a prior Configuration
attempt. The default value is 60 minutes. Generic UI
form
Full-Text-Match- The way the server modifies qualifications from the client. Values are No AR System
Option Configuration
0 — Force leading and trailing wildcards. Generic UI
1 — Ignore leading and force trailing wildcards. form
2 — Ignore leading wildcards.
3 — Remove leading and trailing wildcards.
4 — (Default) Leave query unchanged.
Full-Text-Search- The maximum number of search results returned from the search No AR System
Threshold engine. The default value is 10,000. To limit the number of search Configuration
results (because of constraints on the computer where the search Generic UI
engine is running), reduce the threshold. If you change this option, form
you must restart the BMC Remedy AR System server for the change
to take effect.
Full-Text-Search- During the processing of search results, the server combines results No AR System
Threshold-High from subqueries to arrive at the final result set. If the number of rows Configuration
created during processing exceeds this value, the server returns an Generic UI
error message indicating the search is too complex. The default value form
is 1,000,000.
Full-Text-Search- While processing search results, the server creates a temporary table No AR System
Threshold-Low if the number of FTS matches reaches this value. If the number of Configuration
FTS matches is under this value, the server uses the SQL IN operator Generic UI
for a query on an existing table. The default value is 200. form
GetListEntry- Flag indicating where to format the GetListEntry date. This option is No AR System
Server-Date- used mainly for backward compatibility purposes. Values are Configuration
Format 2 (see page Generic UI
1216) T — Format date on server. form
F — (Default) Format date on client.


configuration
Guest-Restricted- Flag indicating whether guest users receive a restricted read license No AR System
Read when they log in to BMC Remedy AR System. Values are Configuration
Generic UI
T form
F
If this option is not specified, guest users receive a read license.
GUID-Prefix 2 (see Character string used as a prefix for GUID strings generated by No AR System
page 1216) filters. Configuration
Generic UI
form
Hierarchical- Allows you to configure compute delay (in minutes) for hierarchical Yes AR System
Groups-Interval groups. Configuration
Generic UI
The default value is 5 minutes. form
For details on
hierarchical
groups
parameters,
see Controlling
access to
requests for
hierarchical
groups (see
page 1299).
Hierarchical- Allows you to configure the number of threads that will be used for Yes AR System
Groups-Threads computation of hierarchical groups. Configuration
Generic UI
The default value is 1. form
For details on
hierarchical
groups
parameters,
see Controlling
access to
requests for
hierarchical
groups (see
page 1299).
Homepage-Form Path to the systemwide default home page. This home page is used No AR System
only if Configuration
(Component name: Generic UI
com.bmc.arsys. The current server is designated as the server for the home form
server) 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 (see page 431).)
And


configuration
No home page is specified in the BMC Remedy AR System

User Preference form.
Note: If the home page is deleted, this option is cleared, and
the default home page must be re-entered.
Internal-User-Info- Number of shared, linked lists that hold all user-related information. No AR System
Hash-Lists 2 (see This number must be a power of 2. The default setting is 128. The Configuration
page 1216) minimum number is 2. There is no maximum. Generic UI
form
Note: BMC Remedy AR System doe not verify that this number is a
power of 2. If the number is not a power of 2, the AR System server
might behave in unexpected ways.
Internal-User- Time, in minutes, that the AR System server waits before removing No AR System
Instance-Timeout 2 inactive user instances from its internal memory cache. Use this Configuration
(see page 1216) option in an LDAP environment to reduce the frequency of checks Generic UI
against an outside authenticator (if a user's record is in server form
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 No AR System
can appear in the configuration file more than once. When checking Configuration
workflow and connections against itself, the server compares its Generic UI
server name, host name, IP aliases, and any names specified by this form
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.
Jmx-port1 Defines the JMX port number that enables administrators to connect No System >
to JVM by using Java Messaging Extensions (JMX). General >
Server
Default value: 61500 Information >
Ports and
Queues > JMX
Port.


configuration
(See Setting
ports and RPC
numbers (see
page 274).)
License-Timeout Number of hours the BMC Remedy AR System server waits before No AR System
disconnecting inactive users. If a user is holding a floating license, the Configuration
system also frees the license. The default value is two hours. Generic UI
form
Locale-List The installed language packs. Some sample values are No AR System
Configuration
(Component name: en — English Generic UI
com.bmc.arsys. fr — French form
server) it — Italian
ja — Japanese
ko — Korean
pt_br — Brazilian Portuguese
zh_cn — Simplified Chinese
Localized- A semicolon-separated list of message numbers used to modify the No AR System

Messages-To- server's default caching behavior for localized system messages. Configuration
Cache Generic UI
To cache all localized system messages the first time they are form
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 No AR System
mode. Values are Configuration
com.bmc.arsys. T — Run in localized support mode, and use localized form
server) messages if available.
F — (Default) The server does not search for or use localized
strings.
Locked-Workflow- Mode that causes the server to record locked workflow actions in No AR System
Log-Mode 2 (see workflow logs. These actions are written as encrypted strings. Configuration
form
log_backups Maximum number of backup (.bak) log files for the BMC Remedy No AR System
Flashboards server to be allowed, when the log file reaches the Administration
(Component name: Maximum File Size value and a new log file is created. Console >
com.bmc.arsys. System >
flashboardServer ) Default value: 10 General >


configuration
Flashboard
Server
Configuration
> Maximum
Backups.
(See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_category Type of information to be stored in the BMC Remedy Flashboards No AR System

server log file. Administration
(Component name: Console >
com.bmc.arsys. Values are:
System >
flashboardServer ) General >
Alarm — Alarm related logging is stored in the log file.
Flashboard
Flashboard Server — Flashboard server calls logging is stored
Server
in the log file.
Configuration
Flash Util — Flashboard server classes logging is stored in the
> Log Category
log file.
.
Default value: All
(See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_default_format Format for the BMC Remedy Flashboards sever log output when No AR System
log_level parameter for BMC Remedy Flashboards server is set to Administration
(Component name: BASIC or INFO. The log output is generated using Java log4j pattern Console >
com.bmc.arsys. layout. System >
flashboardServer)
Default value: <%t> <%c> <%d> <%l> <%m> %n General >
Flashboard
For more information on log4j pattern layout, see Pattern layout. Server
Configuration
> Log Format.
(See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_detail_format No


configuration
(Component name: Format for the BMC Remedy Flashboards sever log output when AR System
com.bmc.arsys. log_level parameter for BMC Remedy Flashboards server is set to Configuration
flashboardServer) DEBUG. Generic UI
form
Default value: <%t> <%c> <%d> <%l> <%m> %n
For more information on log4j pattern layout, see Pattern layout.
log_filename Name of the BMC Remedy Flashboards server log file. No AR System
Administration
(Component name: Default value: arfbserver.log Console >
com.bmc.arsys.
System >
Flashboard
Server
Configuration
> Log File
Name.(See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_filepath The path for the BMC Remedy Flashboards server log file. No AR System
Configuration
(Component name: Default value: . Generic UI
com.bmc.arsys. form
flashboardServer )
log_filesize Maximum size (in kilobytes) for the BMC Remedy Flashboards server No AR System
log file. Administration
(Component name: Console >
com.bmc.arsys. Default value: 100 KB System >
Flashboard
Server
Configuration
> Maximum
File Size.
(See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_level The level of logging for the BMC Remedy Flashboards server. No AR System
Administration
Console >


configuration
System >
(Component name: Values are:
General >
com.bmc.arsys. BASIC – The minimum log level which logs errors.
Flashboard
flashboardServer ) INFO – The log level which logs errors with information
Server
DEBUG – The maximum log level which gives detailed log
Configuration
information.
> Log Level.
Default value: BASIC (See AR
System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
log_null_value The value to represent a null value in the BMC Remedy Flashboards No AR System
logs. Configuration
com.bmc.arsys. Default value: - form
flashboardServer)
log_viewer The method by which you want to view BMC Remedy Flashboards No AR System
log files. Values are: Configuration
com.bmc.arsys. CONSOLE – The log entries are directed to the stderr ( form
flashboardServer) System.err) of your servlet engine.
FILE – The log entries are saved to a file in the specified log
directory.
Default value: FILE
Log-DSO-Errors- Flag indicating whether to log failed pending distributed operations to No AR System
To-Form the Distributed Pending Errors form. Values are Configuration
Generic UI
T — Log errors to the form. form
F — Do not log errors to the form.
Log-File-Append Flag indicating whether to create a separate *.bak file or to append to No AR System
the existing log file. Values are Configuration
Generic UI
T — Append new log information to the existing file. form
F — (Default) Create a *.bak file.
Log-Form- Bitmask indicating the type of information to log in the common log No AR System
Selected form (AR System Log:ALL). To activate one bit, set this option to its Configuration
value (values are listed under the Debug-mode (see page 1186) Generic UI
(Component name: option). To activate two or more bits, add their values, and set this form
com.bmc.arsys. option to the total. For example, to activate bits 1 and 3, set this
server) 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:



configuration

Log-To-Form Bitmask indicating the information to log in predefined forms (for No AR System
example, AR System Log: API and AR System Log: Filter). To Configuration
activate one bit, set this option to its value (values are listed under the Generic UI
Debug-mode (see page 1186) option). To activate two or more bits, form
add their values, and set this option to the total. For example, to
activate bits 1 and 3, set this option to 5 because bit 1 has a value of
1 and bit 3 has a value of 4. To deactivate a bit, subtract its value
from the value of this option. This option does not apply to the
following bits because no log form is created for their corresponding
applications:

Map-IP-Address IP address mappings that enable alerts to work through firewalls No AR System
when Network Address Translation (NAT) is on. You must set up a Configuration
2 (see page 1216)
mapping for each client computer that has access through the firewall Generic UI
where the client IP address is translated from an internal address to a form
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-AlwaysOn- The size of the memory buffer in bytes to store the logs in memory for Yes AR System
Buffer-Size always on logging feature. Administration
Console >
System >
Default value: 5242880 bytes (5 MB) General >
Server
Information >
Always On
Logging >
BufferSize.
(See Setting
Always On
logging (see
page 339).)
Max-Entries-Per- Maximum number of requests returned by a search. Because users No AR System

Query can also specify the maximum number of requests returned through Configuration
Search Preferences in the BMC Remedy AR System User Preference Generic UI
(Component name: form, the actual maximum is the lower of these values. The default form
com.bmc.arsys. value is no server-defined maximum.
server)


configuration
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 No AR System
reached, the logging cycle restarts at the beginning of the file, Configuration
overwriting existing information. The default value is 0 (no limit). This
com.bmc.arsys. form
option does not apply to the Arfork-Log-File.
server)
Max-Log-History Maximum number of backup (.bak) log files to be allowed when the No AR System
log file reaches the Max-Log-File-Size value and a new log file is Configuration
created. By default, the number of backup log files allowed is 1 and
com.bmc.arsys. form
the maximum number of backup log files allowed is 999.
server)
Max-Notify-Mail- Maximum number of bytes that can be in a line of a mail notification. No AR System
Line-Len 2 (see page Configuration
1216) Generic UI
form
Max-Password- Maximum number of consecutive bad password retries a user can No AR System
Attempts make. If this option is set to 3, the user has 3 chances to log in. If all 3 Configuration
attempts have bad passwords, the user account is marked INVALID. Generic UI
Values are 0 (which turns this feature off) and all positive integers. form
This parameter can be used in conjunction with Display-General-

Auth-Message. See Configuration settings C-D (see page 1168). See
also the description for error 624 (see page 4500).
Max-Recursion- For forms that contain hierarchical data, such as manager and No AR System
Level employee relationships, the maximum number of levels in the Configuration
hierarchy that a recursive query retrieves. Values are any integer Generic UI
greater than 0. The default is 25. See form
ARGetListEntryWithMultiSchemaFields (see page 3848).
Max-Vendor-Temp- Maximum number of temporary tables that can exist on an AR No AR System

Tables System server for a single vendor form. The Configuration
ARGetListEntryWithMultiSchemaFields function stores data from Generic UI
vendor data sources in these tables. By default, only one temporary form
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
(see page 3848).
MaxWorkerThreads The maximum number of worker threads allowed for BMC Remedy AR System
Flashboards server. Configuration
com.bmc.arsys. Default value: 2 form
flashboardServer )
Maximum- Maximum number of concurrent client-managed transactions. The No AR System

Concurrent-Client- default is 10, and the maximum value you can enter is 100. Configuration
Managed- Generic UI
Transactions form
No


configuration
MFS-Environment- Indicates the relevancy weight for the Environment field of a form in AR System
Field-Weight a multiple-form search. The value can be any number between 0 and Configuration
2000. Generic UI
form
Valid values:
0 - 0.9 — Reduces the relevancy weight of the Environment

field.
1 — (Default) No change to the relevancy weight.
1.1 - 2000 — Increases the relevancy weight of the
Environment field.
For more information, see Configuring forms for multi-form FTS (see
page 1424).
MFS-Keywords- Indicates the relevancy weight for the Keywords field of a form in a No AR System
Field-Weight multiple-form search. The value can be any number between 0 and Configuration
2000. Generic UI
form
Valid values:
0 - 0.9 — Reduces the relevancy weight of the Keywords

field.
1.1 - 2000 — Increases the relevancy weight of the Keywords
field.
page 1424).
MFS-Title-Field- Indicates the relevancy weight for the Title field of a form in a multiple- No AR System
Weight form search. The value can be any number between 0 and 2000. Configuration
Generic UI
Valid values: form
0 - 0.9 — Reduces the relevancy weight of the Title field.

1.1 - 2000 — Increases the relevancy weight of the Title field.
page 1424).
Mid-Tier-Service- Password that administrators use to access the mid tier. No AR System
Password Configuration
Generic UI
(Component name: form
com.bmc.arsys.
server)
Minimum-API- Oldest API version with which the server communicates. The default No AR System
Version value is 0, which means that the server communicates with all API Configuration
versions. If the client's API version is less than the specified value, Generic UI
the server refuses to talk with the client, and the client receives a form
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.)
No


configuration
Minimum-CMDB- Oldest CMDB API version with which the server communicates. The AR System
API-Version default value is 3. If the version of a CMDB call is less than the Configuration
specified value, the server refuses the call. This option is independent Generic UI
of the Minimum-API-Version option. form
MinWorkerThreads The minimum number of worker threads allowed for BMC Remedy AR System
Flashboards server. Configuration
com.bmc.arsys. Default value: 2 form
flashboardServer )
Multiple- Flag indicating whether other AR System servers can run on this No AR System
ARSystem-Servers server's host computer. Configuration
Generic UI
(Component name: Valid values: form
com.bmc.arsys.
server) 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- Flag indicating whether multiple assignee groups can be stored in No AR System
Groups 2 (see page row-level security field ID 112. This enables users from multiple Configuration
1216) groups to access the same request. In the past, only one group could Generic UI
be stored in Field 112. form
Valid values:
T — (Default) Allow multiple groups in field ID 112.

F — Do not allow multiple groups in field ID 112.
Options you cannot set or view using the AR System Administration: Server Information form.
Configuration settings N-R

Note

Tip
Configuration options (N-R)

configuration
Next-ID-Commit Flag indicating whether to perform a new commit transaction when the No AR System
2 (see page 1216) system generates the next ID for a record in the database. Configuration
Generic UI
Valid values: form
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- Option that allocates next IDs in blocks instead of one at a time. No System >
Size Allocating in blocks increases performance during create operations. General >
Values are any positive number up to 1000. The default value is 25. (A Server
value of 1 disables the feature.) You can also disable it by removing it Information >


configuration
from the configuration file. You do not need to restart the server for the Configuration
change to take effect. > Next
This setting is always disabled on the Distributed Pending form so that Request ID
DSO can operate correctly. Block Size.
Warning: The use of this option might result in unpredictably large Next- (See Setting
ID sequence gaps. The likelihood of this occurring increases with the administrative
use of multiple servers that share a database. The BMC Remedy AR options (see
System server does not malfunction because of this gap, and it should page 291).)
not be considered a defect.
Notification- Base URL that appears in email notifications. If this option is not used, No AR System
Web-Path the Default-Web-Path option is used. (Notification-Web-Path is Configuration
available because the Default-Web-Path is specified for other Generic UI
applications such as Flashboards, and it might be different from the mid form
tier web path for opening requests in a notification.)
Num-Preload- Total number of preload segments loaded by the preload threads when No System >
Schema- preload threads are configured. See Setting the Preload Tables General >
Segments Configuration option. (see page 369) Server
Information >
(Component
Advanced >
name: com.bmc. Number of
arsys.server)
Preload
Segments.
(See Setting
performance
and security
options (see
page 285).)
Num-Preload- Number of preload threads to use when preload threads are configured. No System >
Threads A value of 0 indicates that preload threads are not used. The maximum General >
value is 30 or twice the number of preload segments, whichever is Server
(Component lower. See Setting the Preload Tables Configuration option (see page Information >
name: com.bmc. 369). Advanced >
arsys.server)
Number of
Preload
Threads.
(See Setting
performance
and security
options (see
page 285).)
Num-selector- Defines the number of threads that can be used to monitor all the live No System >
threads1 client socket connections for IO activity. When the thread detects any General >
activity, it forwards the call to the appropriate queue. Server
Information >
Default value: 1 Ports and
Queues >
Number of
Selector
Threads.


configuration
(See Setting
ports and RPC
numbers (see
page 274).)
Oracle-Bulk- Number of data rows simultaneously fetched from the result set when No AR System
Fetch-Count 2 an Oracle database is queried. The minimum is 1, the maximum is 100, Configuration
(see page 1216) and the default is 50. The higher the value, the more memory is used Generic UI
during data retrieval. form
Oracle-Clob- (Oracle databases only) Flag controlling Oracle CLOB storage. No AR System
Storage-In-Row Configuration
Valid values: Generic UI
(Component form
name: com.bmc. T — CLOBs are created "in row." In-row CLOBs can degrade
arsys.server) CPU performance.
F — (Default) CLOBs are created "out row." Out-row CLOBs can
cause the database to grow rapidly.
Oracle-Cursor- Database setting that matches the setting in the Oracle initialization file ( No AR System
Sharing 2 (see initARS.ora if the BMC Remedy AR System database SID is ARS). Configuration
Valid values: form
(Component
name: com.bmc. FORCE — Use this value if the initARS.ora file includes the
arsys.server) following line: CURSOR_SHARING=FORCE.
SIMILAR — If your Oracle database is set for SIMILAR, use this
value.
Oracle-Search- Flag indicating whether CLOBs can be searched. No AR System

On-Clob 2 (see Configuration
page 1216) Valid values: Generic UI
form
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 (see (Oracle databases only) System ID for the underlying database. No AR System
page 1216) Configuration
Generic UI
form
Oracle-Two-Task (Oracle databases only) Two-task environment setting for the underlying No AR System
1 (see page 1216) database. Configuration
Generic UI
form
Overlay-mode 2 Specifies the default overlay group for the server. Clients that use the No AR System
(see page 1216) default overlay group (all clients other than Developer Studio) will Configuration
retrieve and use objects from the default group. Generic UI
form


configuration
Valid values:
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 (see page 3075).
Per-Thread- Flag indicating whether to create per-thread log files. No AR System

Logging Configuration
form
T — Create per-thread log files.
F — (Default) Do not create per-thread log files.
Peer-listener- Defines the port number where all the cache instances from different No System >
port1 servers communicate with each other. General >
Server
Default value: 40001 Information >
Ports and
Queues > C
ache Peer
Listener Port.
(See Setting
ports and RPC
numbers (see
page 274).)
Plugin 2 (see page File name of one or more plug-ins that the plug-in server loads. The file No AR System
1216) name of the DLL or shared object is provided. The file name might be Configuration
an absolute file name or might be relative to the BMC Remedy AR Generic UI
(Component System installation directory. Add as many entries for this option to the form
name: com.bmc. server configuration file as needed, but specify only one file name in
arsys.server) each option.
Plugin-Log-File Full path name of the file to use if plug-in logging is on (see Debug-mode No AR System
(see page 1186)). Configuration
Generic UI
form
Plugin-Log-Level Option that specifies the type of information printed to plug-in log files. No AR System
Configuration
form
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
).


configuration
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- RPC socket number for the private server queue to which loopback plug- No System >
Loopback-RPC- in API calls should be directed. Values are in the following ranges: General >
Socket 2 (see page Server
1216) 390621-390634 Information >
390636-390669 Ports and
390680-390694 Queues >
Plugin
Loopback plug-ins (such as the Report Creator plug-in) that call back
Loopback
into BMC Remedy AR System use this number to determine the queue
RPC Program
to request. By default, plug-in API calls are directed to a queue that
Number.
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 No AR System
connections only from BMC Remedy AR System servers whose Server- Configuration
Plugin-Target-Password option is set to the same password. If this Generic UI
option is not specified, the plug-in server accepts connections from form
BMC Remedy AR System servers that are not configured to use a plug-
in password.
Plugin-Port 2 (see The port number on which the plug-in server waits for incoming No AR System
page 1216) requests. Configuration
Generic UI
(Component form
name: com.bmc.
arsys.server)
Preference- Option that specifies whether users must use centralized preferences. No System >
Server-Option General >
Valid values: Server
Information >
1 — Users can choose to use a preference server if one is
Advanced >
available.
Preference
2 — Users must use the specified preference server.
Server Option.
3 — Users must use a preference server, but they cannot use
(See Setting
this server as a preference server. If users choose a server that
performance
is not a preference server, a warning is returned.
and security
options (see
page 285).)
Private-RPC- RPC program number that determines the type of queue to which No System >
Socket requests are routed and the number of threads running on that queue. General >
Server
(Component Information >
name: com.bmc. Ports and
arsys.server) Queues >
Server Queue.


configuration
(See Setting
ports and RPC
numbers (see
page 274).)
Private-RPC- Option that designates debug queues. A debug queue is a type of No AR System
Socket (for private queue used by the BMC Remedy AR System Workflow Configuration
debug queue) Debugger. To make any private queue a debug queue, use this syntax: Generic UI
Private-RPC-Socket: rpcNumber Debug For example: Private-RPC- form
(Component
Socket: 390666 Debug Alternatively, you can make a private queue a
name: com.bmc.
debug queue by selecting its Debug check box in the list of queues in
arsys.server)
the Ports and Queues tab of the Administration Console.
RE-Log-File- Location of the Reconciliation Engine log file. No AR System

Location 2 (see Configuration
form
Record-Object- Flag indicating whether the BMC Remedy AR System server records No System >
Relationships the relationships between workflow objects. General >
Server
(Component Note: If using a server group, all servers within the same server group Information >
name: com.bmc. must have the same setting for this option. If they do not, the servers in Configuration
arsys.server) the group inconsistently populate and un-populate the object > Record
relationship database should they be the highest ranked server for the Object
Administration operation when they are restarted. Only the highest Relationships.
ranked server for the Administration operation in the server group will
perform the required object relationship actions when restarted. (See Setting
administrative
Valid values: options (see
page 291).)
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 (see page 2292).


configuration
Record-Server- Server events to log in the Server Events form, which makes server- No AR System
Events related changes available to workflow and API programs. Enter the Configuration
following values, separated by semicolons, for the events to record. Generic UI
form
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
Register-With- Flag that prevents the BMC Remedy AR System server from registering No System >
Portmapper with a portmapper. Use this feature in conjunction with setting specific General >
ports to enable you to run servers on computers that do not have a Server
(Component portmapper. Information >
name: com.bmc. Ports and
arsys.server) Valid values: Queues >
Register with
T — (Default) Register with portmapper.
Portmapper.
F — Do not register with portmapper.
(See Setting
No more than one server should try to register with AR System
ports and RPC
Portmapper in an environment with multiple servers on one computer.
numbers (see
page 274).)
Registry-Admin- Password of the BMC Atrium Web Services Registry admin user. Used No AR System
Password by workflow for the BMC Remedy AR System Web Services Registry Configuration
form. Generic UI
form
Registry-Admin- User name of the BMC Atrium Web Services Registry admin user. Used No AR System
User by workflow for the BMC Remedy AR System Web Services Registry Configuration
form. Generic UI
form
Registry- URL of the BMC Atrium Web Services Registry. Used by workflow for No AR System
Location the BMC Remedy AR System Web Services Registry form. Configuration
Generic UI
form
Remedy-App- Encrypted password that AR System application services such as No System >
Service- Approval Server use to access the BMC Remedy AR System server. General >
Password Server
Information >


configuration
(Component Connection
name: com.bmc. Settings >
arsys.server) Application
Service
Password.
(See Setting
server
passwords,
RPC options,
and plug-in
timeouts (see
page 288).)
Required-Field- Character to add to the label of a field whose entry mode is Required. No The Required
Identifier The default is an asterisk. Field Identifier
field on the
(Component
Configuration
name: com.bmc.
tab of the AR
arsys.server)
System
Administration:
Server
Information
form. (See
Setting
administrative
options (see
page 291).)
Required-Field- Position to add the character that identifies a Required field. No System >
Identifier- General >
Valid values:
Location Server
Information >
(Component 0 — Add the character to the beginning of the field label.
Configuration
name: com.bmc. 1 — (Default) Add the character to the end of the field label.
> Required
arsys.server)
Field Identifier
.
(See Setting
administrative
options (see
page 291).)
RMIRegistryPort Port number for the Remote Method Invocation (RMI) of the selected AR System
BMC Remedy Flashboards server. Administration
(Component Console >
name: com.bmc. System >
arsys. General >
flashboardServer) Flashboard
Server
Configuration
> RMI Registry
Port. (See AR
System
Administration -
Flashboard


configuration
Server
Configuration
(see page 645)
.)
RPC-Non- Flag that enables BMC Remedy AR System on compliant systems to No AR System
Blocking-IO 2 receive remote procedure calls in a nonblocking mode. The mode Configuration
(see page 1216) prevents Generic UI
form
Remote attackers from disabling RPC services.
Invalid or corrupt packets from temporarily disabling the
arserverd process.
Valid values:
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

PHNE_29211 - HPUX 11i
Solaris
108993-38 - Solaris 8
113319-19 - Solaris 9
IBM Does not specify a patch number. Multiple file sets might be
required. (If you do not obtain an IBM® patch, your server might crash.)
Fix for Authorized Problem Analysis Report (APAR) IY61602 -

AIX 5.3
Fix for APAR IY61409 - AIX 5.2
RPC-QUEUE-BY- This option specifies a private queue for a Client type. The option forces Yes System >
CLIENT-TYPE the API calls made by the Client Types to use this private queue. The General >
syntax is: RPC-QUEUE-BY-CLIENT-TYPE: Client-Type Private RPC Server
Queue. Information >
Ports and
For example: RPC-QUEUE-BY-CLIENT-TYPE: 0 390685. Queues >
Client Type to
RPC
Restriction
Mapping.


configuration
(See Setting
ports and RPC
numbers.)
Options you cannot set or view using the AR System Administration: Server Information form.
Configuration settings S-Z

Note
Tip

Configuration options (S-Z)

configuration
Save-Login Flag indicating whether users must log in to client tools. This No AR System
option enables users to save a previous login of their choice. Configuration
Generic UI
Valid values: form.
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 No AR System

requires you to enter a comment at checkin. Valid values: Configuration
Generic UI
0 — (Default) No comment is required. form.
SCC-Comment- Flag indicating whether a source code control integration No AR System

Checkout requires you to enter a comment at checkout. Valid values: Configuration
Generic UI
0 — (Default) No comment is required. form.
SCC-Enabled Flag indicating whether a source code control system is being No AR System
used with BMC Remedy AR System. Configuration
Generic UI
Valid values: form.
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. No AR System
Configuration
form.
0 — (Default) Advisory level.
1 — Enforced level.
SCC-Provider-Name Name of the source code control provider. For example: Visual No AR System
Source Safe. Configuration
Generic UI
form.
SCC-Target-Dir Character string for the source code control system target No AR System
directory. If none is present, this value is NULL. This string is Configuration
limited to 255 characters. Generic UI
form.
Select-Query-Hint 2 (see Text to use in a query hint in the WITH clause of a SELECT No AR System
page 1226) statement when queries are supplied to Microsoft SQL Server Configuration
databases. This option works only for queries triggered by GLE, Generic UI
GLEWF, and GME API calls. If this option is an empty string or form.
is not present, no WITH clause is generated. To determine the
appropriateness of using this feature in your environment,


configuration
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
ServerConnectAttempts Number of attempts, the BMC Remedy Flashboards server tries AR System
to connect to the BMC Remedy AR System server. Flashboard Administration
(Component name: com. waits for the BMC Remedy AR System server to start up and Console >
bmc.arsys.
tries to connect. If the connection fails, the flashboard keeps on System >
flashboardServer ) retrying for the connection, based on number of attempts value. General >
Flashboard
Default value: 10
Server
Configuration
> Server
Reconnect
Attempts. (See
AR System
Administration -
Flashboard
Server
Configuration
(see page 645)
.)
Server-Connect-Name 2 New name for a server in a server group. By default, a server in No AR System
(see page 1226) a server group uses a fully qualified server name with domain to Configuration
identify itself. Others servers in the group use this name to Generic UI
(Component name: com. communicate. To change the server name, add this option to the form.
bmc.arsys.server) 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 (see page 342).
Server-directory 1 (see Full path name of the AR System data directory. This directory No AR System
page 1226) contains support and log files for the AR System server. Configuration
Generic UI
(Component name: com. form.
bmc.arsys.server)
Server-Group-Email- Port number (RMIPort ) for email administration in Email Engine. No AR System
Admin-Port 2 (see page If RMIPort is different from the default (1100 ), set this option to Configuration
1226) the new, port number to enable the server to communicate email Generic UI
administration information to Email Engine during server group form.
processing. For example, in a single Email Engine configuration,
use this syntax:
Server-Group-Email-Admin-Port: 2020


configuration
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- Port number (RMIRegistryPort ) for Flashboards administration No AR System

Flashboards-Admin- in the Flashboards server. If the default Flashboards port Configuration
Port 2 (see page 1226) number is changed, set this option to the new port number to Generic UI
enable the server to communicate Flashboards administration form.
(Component name: com. information to the Flashboards server during server group
bmc.arsys.server) 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 No AR System
name is arsrvgrp.log. For example: Server-Group-Log-File: c: Configuration
\temp\servgroup.log Generic UI
form.
Server-Group-Member Flag indicating whether the server is a member of a server No System >
group. General >
(Component name: com. Server
bmc.arsys.server) Valid values: T and F (default). Information >
Configuration
> Server
Group Member
. (See Setting
administrative
options (see
page 291).)
Server-Name An alias that is always interpreted as the current server. This No AR System
option is used in multiple server installations to differentiate Configuration
(Component name: com. servers. If you specify a value for this option, enter the value Generic UI
bmc.arsys.server) after the -h option when you use the arreload command-line form.
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 (see page
1228).
Server-Plugin-Alias 2 Alias of a plug-in server. When the BMC Remedy AR System No AR System
(see page 1226) server calls a plug-in server, it must determine whether the plug- Configuration
in server name is an alias. Aliases can direct the BMC Remedy Generic UI
(Component name: com. AR System server to access a plug-in server running on a form.
bmc.arsys.server) different host or listening at a specified port number. The syntax
is


configuration
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- Number of seconds in which the plug-in server must respond to No AR System
Timeout a call before an error is returned. The minimum value is 0. The Configuration
maximum is 600. Generic UI
form.
Default: 60
Server-Plugin-Target- Encrypted password used to call a plug-in server. The BMC No AR System
Password Remedy AR System server uses this password whenever it Configuration
communicates with a plug-in server running on the specified host Generic UI
and port. The syntax is {{Server-Plugin-Target-Password: form.
<hostName>:<portNumber>: <encryptedPassword>
Server-Side-Table- For server-side table fields, the number of requests (or size of No System >
Chunk-Size the chunk) that the server retrieves at one time from the General >
database and stores in memory to process during filter or filter Server
guide actions. The server then retrieves, stores, and processes Information >
the next chunk until all requests are processed. The value 0 Configuration
causes the server to retrieve an unlimited number of requests. > Server Table
The default is 1000 requests. Specifying a lower value causes Field Chunk
the server to process smaller chunks, which reduces server Size.(See
memory use but results in slower processing because the server Setting
must access the database many times, especially for large administrative
tables. Specifying a higher value causes the server to retrieve options (see
and process large chunks of data and access the database page 291).)
fewer times. This results in improved performance at the cost of
increased memory use.
Server-Stats-Rec- Interval (in seconds) at which the server records server statistics. No AR System
Interval Configuration
Default: 60 seconds Generic UI
form.
Server-Stats-Rec-Mode Server statistics recording mode. This option determines what No AR System
information is recorded in the server statistics form. Configuration
Generic UI
Valid values: form.
0 — (Default) Recording is off.

1 — The server records only cumulative queue statistics
(the sum of all the individual queue statistics).


configuration
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 in BMC Remedy ITSM Deployment
documentation.
Set-Process-Timeout Number of seconds the BMC Remedy AR System server waits No AR System
before ending a Set Fields process that did not finish. Values are Configuration
1 through 60. Generic UI
form.
Default value: 5
SQL-Log-File Full path name of the file to use if SQL logging is on (see Debug- No AR System
Generic UI
form.
SQL-Secure- (Microsoft SQL Server only) Flag indicating the type of No AR System
Connection authentication to use to connect BMC Remedy AR System to a Configuration
Microsoft SQL Server database. Generic UI
form.
Valid values:
T — Windows Authentication
F — SQL Authentication
SQL-Server-Set-ANSI- Option that causes the server to issue a SET ANSI_NULLS ON No AR System
Defaults 2 (see page 1226) command. Configuration
Generic UI
form.
Submitter-Mode Flag indicating whether the Submitter field can be changed and No AR System
whether the submitter of a request must have a write license to Configuration
modify it. Generic UI
form.
Valid values:
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 No AR System

(see page 1226) spaces) that identify informational or warning messages that the Configuration
system should suppress. Only server warnings and notes can be Generic UI
suppressed. form.
System-Logging- Bitmask that sets logging options for the operating system. No
Options 2 (see page 1226)
Valid values:


configuration
0 — (Default) Use normal operating system logging. AR System

Bit 1 (value = 1 ) — Suppress logging to the operating Configuration
system log file. Generic UI
form.
System-Messages- Flag to specify whether system messages appear in the prompt No AR System
Displayed bar or a pop-up box. Configuration
Generic UI
Valid values: form.
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 No System >
dispatcher is randomly assigned to an available port. (TCD General >
(Component name: com. stands for transaction control daemon.) Server
bmc.arsys.server) Information >
Ports and
Queues >
Server TCP/IP
Port. (See
Setting ports
and RPC
numbers (see
page 274).)
Thread-Log-File Full path name of the file to use if thread logging is on (see No AR System
Debug-mode (see page 1186)). Configuration
Generic UI
form.
Track-Admin-Op- Flag indicating whether the BMC Remedy AR System server No AR System
Progress 2 (see page 1226) populates progress information (if any) during long-running Configuration
administrative operations, such as definition imports. Generic UI
form.
Valid values:
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 No AR System
(see page 1226) year as a four-digit year. For example, if the two-digit cutoff year Configuration
is 2040: Generic UI
form.
Two-digit years fall between 1941 and 2040.


configuration
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 No System >
executing queries during workflow that have full text indexed General >
fields in the qualification. If this option is not used, the server will Server
use the search capability of the database. The options are T Information >
(use FTS in workflow) and F (do not use FTS in workflow). FTS > Use FTS
in Workflow.
(See FTS tab

configuration
options (see
page 546).)
Use-Password-File Validation mechanism for unregistered AR System users. To set No AR System

this value, use the Authenticate Unregistered Users check box in Configuration
the EA tab of the AR System Administration: Server Information Generic UI
form. Windows Indicates whether the Windows domain service is form.
used to validate users not registered with BMC Remedy AR
System.
Valid values:
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.
Valid values:
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- Flag indicating whether the server name specified by the Server- No AR System
Name-In-Stats 2 (see Connect-Name (see page 1228) option is used as the value for Configuration
page 1226) the Server Name field when Server Statistics form entries are Generic UI
created. form.
Valid values:
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.


configuration
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- No AR System
Generic UI
form.
VersionControl-Object- Option indicating whether the object modification log is enabled No AR System
Modification-Log-Mode or disabled. When the log is enabled, it records every change to Configuration
AR System objects in your system (see Version control in BMC Generic UI
Remedy AR System (see page 2324)). form.
Valid values:
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 (see
page 263).
VersionControl-Object- Option indicating whether the AR System server writes a No AR System

Modification-Log-Save- definition file each time an object is created or changed (see Configuration
Definition-Files Version control in BMC Remedy AR System (see page 2324)). Generic UI
This option is effective only when the object modification log is form.
enabled.
Valid values:
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
page 263).
VersionControl-Object- Option indicating whether object reservation is enforced or No AR System

Reservation-Mode disabled. When object reservation is enforced, users can reserve Configuration
server objects, and BMC Remedy AR System prevents other Generic UI
users from modifying the reserved objects (see Version control form.
in BMC Remedy AR System (see page 2324)).
Valid values:
0 — (Default) Disabled
10 — Enforced
You can also set this option by using the Object Reservation
page 263).

Notifications about changes to centralized configuration

settings
When the AR System server detects any changes to the centralized configuration settings, it sends
a notification, after a 5 second delay, to the components regarding the change. Each affected
component then updates the setting across all instances.
For example, when you change the value of the arsystem.session_timeout setting, the AR
System server notifies BMC Remedy Mid Tier regarding the change. The mid tier, in turn, updates
the setting across all mid tiers in that cluster within 30 seconds.
Updating configuration settings by using the AR System

Configuration Generic UI form
Use the AR System Configuration Generic UI form from the BMC Remedy AR System
Administration Console to add or modify configuration settings for centralized components.
This topic provides the following procedures:
To add a new configuration setting (see page 1236)

To modify an existing configuration setting (see page 1236)
To disable an existing configuration setting (see page 1236)
To delete an existing configuration setting (see page 1236)
Note
You can continue to change the configuration settings for the following
components by using the listed form or tool:
BMC Remedy AR System server — AR System Administration:Server
Information form
BMC Remedy Approval Server — AP-Admin-ServerSettings form
BMC Remedy Mid Tier — Mid Tier Configuration Tool
You can use the AR System Administration:Plugin Server Information form form to
change the configuration settings for Java plug-in server.
You can use the AR System Configuration Generic UI form form for BMC Remedy
Email Engine configuration settings and any other configuration settings that are
not available in the preceding forms.

To add a new configuration setting
> General > Centralized Configuration.
2. In the AR System Configuration Generic UI form, from the Component Name list, select the
component to which you want to add a setting.
3. Click Add.
4. Enter the name of the setting that you want to add and its value.
For a complete list of configuration settings, see Configuration settings (see page 1147).
5. Click Apply.
6. Click Close.
To modify an existing configuration setting
appropriate component.
3. From the settings table, select the setting that you want to modify.
4. Make the required change, and click Apply.
5. Click Close.
To disable an existing configuration setting
3. From the settings table, select the setting that you want to disable.
4. Prefix the setting value with a hash symbol (#) to comment it out, and click Apply.
5. Click Close.
To delete an existing configuration setting
3. From the settings table, select the setting that you want to delete, and click Delete.
4. Click Apply and Close.

Service failover
A companion service is a process that the operating system starts (typically, when the system
starts up) or that armonitor starts. These processes communicate with the AR System server by
using the BMC Remedy AR System API to get their work and to create or change entries. In the
BMC Remedy AR System environment, companion services provide services such as the Email
Engine sending outgoing emails and handling incoming emails. You can deploy these services in a
server group, which provides resiliency if something fails. The servers in the group cooperate to
manage service failover. The server group manages when the companion services become active
to perform tasks and when they are suspended. Also, the companion services are tracked and can
fail over independently of any AR System server.
In this topic:
Monitor service failover (see page 1239)
Companion services periodically assert their current state in the form of a heartbeat. This heartbeat
informs the AR System server of the companion service's state. When the AR System server does
not detect a companion service's heartbeat, it instructs another companion service to take over.
Note
Companion services do not have to run on the same computer as the AR System server.
Furthermore, multiple companion services can run on the same computer.
The following figure shows an example of a server group with companion services. Two
companion services (Email Engine instances) access the AR System server group through a load
balancer.
Example configuration of a server group with companion services

The load balancer provides a single connection point, attempts to direct the load across all nodes
in the server group, and routes clients to active nodes in the server group when a node is inactive
due to a failure. Clients access the server group through the load balancer.
One companion service can perform multiple services. In this example, one Email Engine instance
can provide a service for sending outgoing emails and another service for handling incoming
emails. In such a configuration, each companion service can own, or have exclusive rights to
perform work on, any number of services. This configuration enables both companion services to
process work. (However, only one companion service can own a given service at a time.)
The companion service, in this case, would house two service providers (Email Engine instances).
The service providers' states are stored in a AR System form, and the server group manages those
states.
If the AR System detects that a companion service's heartbeat has stopped, it can instruct
another companion service to take over. Each service provider can fail over independently of the
other servers and independently of a given AR System server.
To ensure high availability in a server group environment, the email engine must point to
the load balancer or the AR server name.

Monitor service failover

The following forms enable you to monitor or manage failover:
AR System Service Failover Ranking — The form that you use to manage the ranking of
each service provider. You can view and change entries in this form. To change the ranking
of a service provider, see Changing the ranking of a service provider (see page 1242).
AR System Service Failover Whiteboard— A form that stores the current status of all
service providers. You can use this form’s entries to see which clients are:
Providing a service
Waiting to provide a service
Unavailable
Warning
Do not modify the existing workflows on these forms.
The following topics provide information about service failover:
Service provider states (see page 1239)

Service failover ranking entries (see page 1241)
Changing the ranking of a service provider (see page 1242)
Naming conventions for service names (see page 1242)
Email engine service failover in a server group (see page 1243)
Service provider states

A single companion service can provide multiple services. Each service has a state that is stored in
the AR System Service Failover Whiteboard form.
State transitions

Service provider states
State Description
Active The service provider is processing requests.
Suspending The service provider has been told to complete or abort any in-progress request and relinquish ownership of the
service.
Waiting The service provider is available to process requests.
Unavailable The heartbeat from the service provider is no longer being detected. (As part of a graceful shutdown, the service
provider can assert that it is no longer available.)
Within a server group, one node has an active service failover controller, which drives state
transition for the group. If the AR System server with that node goes down, another node in the
server group receives ownership of the controller. For more information about the controller, see
Service Failover Ranking Entries (see page 1241).
Service provider state transitions
Original New state Changes driven by the AR Changes driven by the service provider
state System server
Active Unavailable The AR System server did not The service provider has shut down and is no longer available.
detect a heartbeat, which
indicates that the service
provider is not working or is
unavailable to take ownership of
a service.
Waiting Unavailable The AR System server did not The service provider has shut down and is no longer available.
provider is no longer available to
take ownership of a service.
Suspending Unavailable The service provider gracefully completes all the in-progress
requests and then is no longer available.

Original New state Changes driven by the AR Changes driven by the service provider
state System server
The AR System server did not

provider is still gracefully
suspending work in progress.
Active Suspending The AR System server intends to Not applicable. The service provider cannot assert a
fail over the service from one suspending state.
service provider to another. The
AR System server gives the
active service provider the ability
to gracefully finish any work that
is currently under way.
Active Waiting Not applicable. Only the service The service provider has completed its requests and intends to
provider can assert a waiting give the AR System platform the opportunity to recalculate the
state. highest ranked service provider for the service. The AR System
server would detect that there is no active service provider for
the service, examine the ranking criteria and available service
providers, and give ownership to (that is, make active) the
appropriate service provider.
Waiting Active The AR System server intends to Not applicable. Only the AR System server can determine and
fail over the service from one assign ownership of the service.
service provider to another. The
AR System server indicates to a
waiting service provider that it
should take ownership of the
service and begin processing.
Related topic
Verifying the state of the service provider (see page 1239)
Service failover ranking entries

The controller creates an entry in the AR System Service Failover Ranking form (see page 1237)
under the following circumstances:
When an entry is created in the AR System Service Whiteboard form

When a waiting or active provider is examined as a possible highest rank
If no other rankings exist for the service, the entry receives a ranking of 1. If other rankings exist,
the entry receives a null ranking (that is, an unset ranking), which is treated as the lowest ranking
(MAXINT (232 - 1)). This ranking assumes that existing providers are already working, and a
failover is not triggered when you introduce a new provider.

Rank is in ascending numerical order. Service providers with the numerically lower rank are
chosen before ranks of greater value (negative-valued rank takes a higher precedence over
positive-valued rank). If two providers of the same service have the same rank, then the service
failover controller chooses one.
Changing the ranking of a service provider

Administrators can use the AR System Service Failover Ranking form to view and manage
rankings.
To change the ranking of a service provider
1. In a browser, open the AR System Service Failover Ranking form in search mode:
http://midTierServer:portNumber/arsys/forms/ARSystemServer/AR+System+Service
Failover+Ranking/
2. Perform a search to see the entries in the form, and select the required entry.
3. Change the value in the Rank field.
The valid value for this field is any integer.
Note
A negative-valued rank takes precedence over a positive-valued rank.
4. Save the form.
Related topic
Service failover ranking entries (see page 1241)
Naming conventions for service names

Service names are unique and use the following syntax to ensure uniqueness:
nameSpace://service-name
nameSpace uniquely identifies the type of service: com.bmc.arsys.emaildaemon.

service-name is specific to the implementation of the service.
Note
For Email Engine, the service-name is made up of two parts: mailboxFunction

/mailboxName.

mailboxFunction refers to the incoming or outgoing service.

mailboxName refers to the name of the mailbox from the AR System Email
Mailbox Configuration form.
For example:
com.bmc.arsys.emaildaemon://outgoing/IN-REMDEV
com.bmc.arsys.emaildaemon is the nameSpace.

outgoing/IN-REMDEV is the service-name.
Related topic
Email engine service failover in a server group

In this topic:
Service failover scenario 1 (see page 1243)

Service failover scenario 1

Consider a scenario where you configure BMC Remedy Email Engine in a server group
environment, behind a load balancer, and one of the AR System servers goes down. Since
everything is routed via the load balancer, the associated email engine service continues to run.

To configure Email engine behind a load balancer, perform the following steps:
1. Open the EmailDaemon.properties file located in the ARSystemInstallDir\

BMCARSystem\AREmailfolder and modify the following properties to point to the AR
System server alias:
com.bmc.arsys.emaildaemon.serverName.TCP
com.bmc.arsys.emaildaemon.serverName.Password
com.bmc.arsys.emaildaemon.serverName.Language
com.bmc.arsys.emaildaemon.serverName.Interval
com.bmc.arsys.emaildaemon.Servers
com.bmc.arsys.emaildaemon.serverName.RPC
com.bmc.arsys.emaildaemon.serverName.Authentication
2. Open the C:\WINDOWS\system32\drivers\etc\hosts file and add the following alias entry,
and save the file:
IPAddress serverName
Where,
IPAddress is the IP address of the load balancer
serverName is the server name alias of the load balancer

Consider another scenario, where you configure Email Engine in a server group environment,
behind a load balancer, and one of the Email engine services (inbound email) goes down. The
second email engine service now handles both the inbound and outbound services.

Note
When you configure two Email engines (Email Engine1 and Email Engine2) in a server
group environment, by default, Email Engine1 will be the Rank 1 server for both inbound
and outbound services.
To configure Email Engine1 as the primary server for inbound, and Email Engine2 as the primary
for outbound, you must perform the following steps:
1. Open the AR System Service Failover Ranking form.

For the following entries, change the values in the Rank field to 2.
Entry for Email Engine1 outbound service.
Entry for Email Engine2 inbound service.

In this scenario if you have multiple email engines, where multiple mailboxes are configured. In
such scenarios you can set ranking 1 for mail boxes from either of the email engines. For example,
you can set ranking 1 for incoming mail boxes on one Email Engine and set the ranking 1 for
outgoing mail boxes on another Email Engine. You can specify these rankings in the AR System

Service Failover Ranking form. Also, when you have multiple mailboxes (service names), all those
entries are populated in the AR System Service Failover Ranking form. See, Changing the ranking
of a service provider (see page 1242).
The following diagram illustrates the scenario.
Related topics

Setting failover rankings for servers and operations (see page 345)
Security administration
This section describes how to administer BMC Remedy AR System security. Topics include:
Creating users, groups, and roles (see page 1247)

Access control (see page 1273)
Setting up an authentication alias (see page 1328)
Restrictions when logging in to a BMC Remedy AR System server (see page 1332)
Defining your user base (see page 1333)

Understanding database security issues (see page 1339)

Using audit records (see page 1341)
Creating users, groups, and roles

These sections provide an overview of BMC Remedy AR System users, groups, and roles:
Creating and managing users (see page 1247)

Adding and modifying user information (see page 1249)
Creating and managing groups (see page 1255)
Creating and mapping roles (see page 1266)
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 (see page 1249).
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 (see page 1248)

To modify user information (see page 1248)
To delete users (see page 1248)
To enable users to change user record information (see page 1249)

To create users
1. Log in to a browser.
If you are the first administrator to log in, you must log in as Demo and leave the Password
field empty. (BMC Remedy AR System user names are case-sensitive, which means that
you must type Demo, not demo or DEMO.)
During initial installation, the Demo user is installed without a required password. To keep
BMC Remedy AR System secure, add a password for this user as soon as possible.
2. From the AR System Administration Console, click System > Application > Users /
Groups / Roles > User.
The User form opens in Search mode.
3. Choose Actions > New to switch to New mode.
4. Enter information in the appropriate fields, as described in the User form fields table (see
page ).
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
2. Click Search to retrieve a list of defined users.
4. Choose Actions > Delete.
A confirmation box appears to verify that you want to delete the selected users.
5. Click OK.

5.
Warning
If you delete the Demo user before you create another Administrator user, you
lose administrator privileges.
To enable users to change user record information
1. Open the User form in BMC Remedy Developer Studio.

2. Make the User form's Assigned Tofield visible. (By default, the field is hidden.)
a. Double-click the Assigned To field to open the field Properties dialog box.
b. In the Display tab, clear the Hidden check box.
3. Give the Assignee group Change permission for the Password, Default Notify
Mechanisms, or Email Address fields.
4. Give public "visible" permissions.
See Field permissions (see page ).
5. Save your changes, and close BMC Remedy Developer Studio.
6. In a web client, open the AR System Administration Console, and click System >
Application > Users / Groups / Roles > User.
The User form opens in Search mode. The Assigned To field is visible in the User form.
7. Retrieve a list of defined users.
9. Copy the Login name to the Assigned To field to make the user the Assignee.
By using the Assignee group, you enable the user to modify the user's password, default
notification mechanism, or email address.
You can also make the user the Submitter by entering the same name in the Login name
field and in the Creator field.
Adding and modifying user information
Important
If you use BMC Remedy AR System-based applications, set up users in each

application's People form, not in the User form. For more information, see the application
documentation.
In BMC Remedy AR System, you can have registered users and guest users. Each type of user
has different privileges within the system, as discussed in the following sections.

You enter data in the User form to define the components that work together to determine each
user's access to BMC Remedy AR System: login name, password, group membership, and license
type. You also define notification information for each user in this form. For information about the
restrictions for creating or modifying user information, see Restrictions (see page 1254).
To grant a user permission for BMC Remedy AR System objects, add the user to the groups to
which access will be given. To make a user part of a group, choose the appropriate group from the
Group List menu in the User form. (Multiple group names in the Group List field are separated by
spaces.) You can select from the reserved BMC Remedy AR System groups.
Notes
If the group information is returned through external authentication, you cannot be

a part of any administrator group. You can be a part of the administrator group
only from the User form. For information about setting up for external
authentication, see Configuring the AR System server for external authentication
(see page 260) and Specifying internal and external authentication (see page 830)
.
You can get group information from external authentication only if the Group List
(see page 1251) is NULL.
For more information, see Groups in BMC Remedy AR System (see page 1276).
User form in new mode


The following table lists the key fields in the User form.
Key fields in the Roles form
Area name Field Description
User Login Name Identifying name that the user enters into the User Name field when logging in to BMC Remedy
Information AR System. The name can be the same or different than the user name by which this user is
known to the underlying operating system. The dynamic group with an ID of 60988 has read
access to this field, enabling the user to view this field if a password policy is established. See
User 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
Information field's length is 30 bytes, so you can enable users to enter as many as 30 bytes.
Note: Users cannot enter a 28-character password, or an error will occur during authentication.
The Password field is encrypted into the database by using a one-way hash (SHA-1), so
unauthorized users cannot retrieve passwords in clear text, for example, to log in to applications.
To enhance system security, select a password that is different from one used for another
purpose. If unsecure passwords are needed for applications, store the password in a character
field rather than the Password field (field 102). If the Password field is left blank, the BMC
Remedy AR System server does not validate the password with the user's Windows or UNIX
password, unless you configure the server to cross-reference a blank password. See Cross-
referencing blank passwords (see page 831). The dynamic group with an ID of 60988 has read
access to this field, enabling the user to view this field if a password policy is established. See
User Group List

Information

The access control groups to which the user belongs. If you leave this field empty, the user has
only basic Submitter, Assignee, Assignee Group, or Public permissions. Specify groups by name
or ID, as defined in the Group form. User permissions are determined in the Group List field of
the User form. If you later change the Group ID for a group, the users originally assigned to the
group are still attached to the old ID. If no group has the old ID, these users lose access to any
BMC Remedy AR System object for which they do not have permission through another group. If
you choose to This field is limited to 4000 bytes, including expanded strings. See Groups in BMC
Remedy AR System (see page 1276).
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
Information Group List group are calculated by the server based on the groups that the User belongs to. This is a
display-only field, and the field ID is 121. To search in this field in a query-by-example, enter the
ID number of a computed group. To enter more than one computed group ID, include semicolons
after each ID. You must enter the computed group IDs in the same order in which the names
appear in the Computed Group List field when the user's record is displayed. In the following
examples:
The ID for Computed Group 1 is 5678.

The ID for Computed Group 2 is 6789.
You can also use the Advanced Search bar with the LIKE operator. Include the semicolon
with the complete ID.
To search for users who are members of Computed Group 1, enter:

'Computed Group List' LIKE "%5678;%"
You can also enter a partial ID for the computed group.
To search for users who are members of both Computed Group 1 and Computed Group
2, enter:
'Computed Group List' LIKE "%56%" AND 'Computed Group List' LIKE "%89%"
User Full Name Full name of a user. By default, this name appears in the Results pane of the User form when
Information users perform a search operation.
User License Type Type of license that the user is assigned: Read , Restricted Read , Fixed, or Floating. The default
Information is Read. See License types overview (see page 88) for further descriptions of these types.
User Application List of application licenses granted to the user. For example, BMC Change Mgmt User Fixed,
Information License where BMC Change Mgmt is the name of the application and User Fixed is the type of license.
BMC Remedy AR System automatically populates this field according to information entered in
the application's People form.
Note: To use BMC Remedy AR System-based applications from BMC Software, users need an
BMC Remedy AR System user license (to access the BMC Remedy AR System server) and an
application user license (to access the application).
User Default Method by which the user is notified for Notify filter and escalation actions when User Default is
Information Notify specified. The default setting on the User form is Alert.
Mechanism
Email address used to notify the user if email is the notify method.

User Email
Information Address
User Status Defines the status of the user account. This field is for information only. It does not change the
Information status of a user's account. This field is set through workflow if you set a password policy. See
Enforcing a password policy introduction (see page 1310). The options are:
Current---The account is in use.

Disabled---The account is no longer in use.
User Allowed Allows the user to make API calls using only the client types mentioned in the Allowed Client
Information Client Types Types field.
To enter more than one client type ID, include semicolons after each ID. In the following
example, the user can make an API call only to BMC Remedy Mid Tier, BMC Remedy Developer
Studio and BMC ProactiveNet Performance Management.
If the user makes an API call to the Client Type not assigned in the Allowed Client Types field,
the API call fails with the following error:
ARRER 8937: You do not have permission to the client operation.
If the Allowed Client Type field is left blank, the user can make API calls using any client type.
For more information on the list of Client types, see List of Client Type ID (see page 2794).
Password Disable Disables password management for the user. If this check box is selected, when the User
Management Password Password Management Configuration form is updated, the user is not affected. For more
Management information about password management, see Enforcing a password policy introduction (see
For This page 1310).
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
Management Password field when a user's 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
Management Password prompted to change the password. After the password is changed, the check box in the User
Change on form is automatically cleared through workflow.
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
Management Warning changed.
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
Restrictions for users and groups

You cannot create other users with more administrative rights than yourself, and you cannot modify
your own rights.
The new restrictions are applied to prevent:
Creation of an administrative user by a non-administrative user.

Creation of an administrative user with access to more overlay groups than the
administrative user who created them.
The following restrictions are applied before and after you create or modify any user in the User
and Group form.
1. Only an administrator can create, modify, or delete other users belonging to the
Administrator, Sub-Administrator, Struct Admin, or Struct Sub-Admin groups.
A user must have Group ID 1 (AR Administrator) in the group list to create/modify
/delete another user with any of the four administrative class groups in their group
list.
2. No Admin user can create or modify a user (themselves included) with lesser administrative
restrictions than the user making the modification.
For example, an administrator user with Overlay Group 1 cannot create or modify users with
no overlay groups. Consider a situation where you have created an ABCGroup with an
Overlay Group set to 1. User ABCAdmin is part of Administrator group and ABCGroup.
However, ABCAdmin is restricted only to the ABCGroup. ABCAdmin can change (create
/modify/delete) any user belonging only to the ABCGroup. For more information about
creating a group as an overlay group, see Creating groups (see page 1255).
A user cannot create another admin user with the ability to modify base objects if
they themselves cannot do it.
BMC recommends that you should restrict your users to make modifications only to
custom objects and overlays.
3. Only an unrestricted administrator can create, modify, or delete groups that restrict a user’s
administrative capabilities.
Only an administrator with no overlay specific groups can create, modify, or remove
overlay specific groups.

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 (see page
1255).
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 groups (see page 1255) and Adding and modifying user
information (see page 1249)
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 (see page ).
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 (see page 1249), to assign individual users to
the appropriate groups.
Use the Group form (shown in the following figure) in a browser to create and manage the access
control groups to which you grant or deny access to AR System objects. BMC recommends that
you should restrict your users to make modifications only to custom objects and overlays.

Note
You must log on as an Administrator to work with the Group form.
Group Information form — New mode
The following table lists the fields you can set the Group form.
Fields in the Group Information form
Field Description
Group Name of the access control group. Use this name in the Group list field in the User form and in the Permission and
Name No Permission lists when you are defining BMC Remedy AR System object permissions. Every group name should
be different. Use caution when creating group names that include spaces, because group names in the Group list
field on the User form are separated by spaces. For example, if you have a group named CUSTOMER_SUPPORT,
you should not create a group named CUSTOMER or a group named SUPPORT.
Group ID Integer ID that is the recognized identity of the group. The ranges are:
0 – 1000 — For AR System groups and current AR System applications

1000 – 1049, 1061 – 13004, 13021 – 13999, 14102 – 14450, and 14452 – 14998 — For non-BMC regular
and computed groups
1050 – 1060, 13005 – 13020, 14000 – 14101, and 14451 — Reserved for current AR System applications
14999 – 59999 — For current and future AR System applications
60000 and 60002 – 60099 — For non-BMC dynamic groups

60001 and 60100 – 60999 — For AR System application dynamic groups

61000 – 99999 — For AR System applications
100000 – 999999999 — For non-BMC regular and computed groups
1000000000+ — For BMC company permissions
If you use the same ID with multiple group names, you must keep the Group type the same for each because you
are creating aliases for the same group. To make sure that you do not create duplicate Group IDs, use Remedy
Administrator to build a unique inde on the Group ID field in the Group form. (See Defining indexes (see page 2402).)
The Group ID defines the priority of a group when a user obtains a floating license. See About floating licenses in a
license pool (see page 1335).
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),
Type and Change (modify field contents). Specify None to disable all access for the group without deleting the group
itself. The group remains as a placeholder (and can be restored in the future), but all permissions for the group are
lost. To define a group used only for notifications, create a group with the type None. See Field permissions (see
page 1284).
Long Additional information about a group. The text should be descriptive of the group because it appears by default in
Group the Results pane in the mid tier when listing groups.
Name
Group The group category, such as Regular, Dynamic, or Computed, which is described in Regular, computed, and
Category dynamic groups (see page 1277). To define a dynamic group, use a group ID in the range of 60000 to 60999. On the
form containing requests to which you want to define row-level access, add a field with a field ID that is the same as
the dynamic group ID. You can populate a dynamic group field with a group name, role name, or the name of an
individual user. Dynamic Groups are used only to control access to requests (row-level access). To define a
computed group, select Computed Group as the group category and enter a qualification string in the Computed
Group Definition field.
Parent The parent group, if any, of the current group. This field is optional. If a parent group is assigned, members of the
Group parent group have the same rights as members of the current group to objects that allow permissions inheritance. A
group can have at most one parent group. Any regular or computed explicit group can act as a parent group, except
for Administrator, Sub Administrator, and Customize. Implicit groups cannot be used as a parent group. (Implicit
groups include Assignee, Submitter, Assignee Group, and dynamic groups.) To assign a parent group, the parent
group must already exist. Select the parent group from the drop-down list. For:
An overview of hierarchical groups, see Using a parent group for permissions inheritance (see page 1280).
Information about setting permissions inheritance for an object, see Assigning permissions for individual or
multiple objects (see page 1305).
Information about row-level access control and hierarchical groups, see Controlling access to requests for
hierarchical groups (see page 1299).
Overlay Use the setting to define the group as an Overlay Group. The Overlay Group option on the Group Information Form,
Group provides the following access options:
Overlay Group field set to 1: When a group assigned to the user has the Overlay Group field set to 1, the
user is restricted to working on overlay and custom mode objects. In Developer Studio, the user can work
only in Best Practice Customization mode.
Overlay Group field set to 0: When a group assigned to the user has the Overlay Group field set to 0, the
user is restricted to working on base mode objects. In Developer Studio, the user can work only in Base
Developer mode.
Overlay Group set to (clear): When the Overlay Group is set to (clear), the Group provides no restrictions on
access to base, overlay, or custom objects.
Overlay Group field set to 999999999: When a group assigned to the user has the Overlay Group field set to
999999999, the user can work only in read-only mode on all base, overlay, and custom objects.

For more information, see Groups in BMC Remedy AR System (see page 1276) and Operations on objects restricted
by development mode (see page 2342).
Note: Do not assign an overlay to a computed group. If you assign an overlay to a computed group, the ARERR
8821 warning occurs and the computed group is saved with Overlay Group as NULL in the AR System server.
Note: Users must have administrator or sub administrator privileges on the AR server to access Developer Studio.
Computed Qualification string that defines a computed group. Construct the string from any valid combination of explicit group
Group IDs, explicit group names (in double quotation marks), user names (in single quotation marks), and operators such
Definition as AND, OR, and NOT. Optionally, use the AND, OR, NOT, Append Group, Append User, and parentheses buttons
to build the qualification string.
Examples
12000 OR 12001 — Includes all users in group ID 12000 or group ID 12001.

"A" OR "B" — Includes all users in group A or group B.
"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 (see page 1335). If
Licenses this field is missing from the Group form, you can add it using Remedy Administrator. Use field ID 115. See
Creating data fields (see page 2594).
Application Manually enter the information for this field. You can add more than one entry of application names and number of
Floating licenses, separated 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 (see page 2594).
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
Identifier different applications. You can use the unique identifier to differentiate the two.
Datatag Tags the data record as needed. This field is optional. For example, it can store the name of the application which
uses this group.
Note
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 (see page 1249).
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 (see page 1257).
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 (see
page 2783) 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 (see page 1276)

Creating groups (see page 1255)
Access level options for administrators (see page 1269)
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 This form is used for all Flashboard, Flashboard Variable and Flashboard
/Write 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: Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
actlink_auto
actlink_call
actlink_dde
actlink_goto
actlink_group_ids
actlink_macro
actlink_macro_parm
actlink_mapping


Type
actlink_message
actlink_open
actlink_process
actlink_push
actlink_serviceaction
actlink_set
actlink_set_char
actlink_sql
actlink_wait
arcontainer
arctr_group_ids
arctr_subadmin
arreference
arschema
char_menu
char_menu_dd
char_menu_file
char_menu_list
char_menu_query
char_menu_sql


Type
cntnr_ownr_obj
escal_mapping
escalation
AR System Metadata: field Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
field_char
field_column
field_curr
field_dispprop
field_enum
field_enum_values
field_permissions
field_table
AR System Metadata: filter Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
filter_call
filter_goto
filter_log
filter_mapping
filter_message
filter_notify
filter_process
filter_push


Type
filter_serviceaction
filter_set
filter_sql
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
schema_join
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: Read This form is used by the Analyzer to read configuration data.
Server Information
AR System Ignored Analyzer Read This form is used by the Analyzer to store results marked as Ignored.
Results /Write
User Read This form is by the Analyzer to read user permissions.
AR System Object Read This form is used to calculate related objects. It is used extensively in
Relationships 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 These forms are used to read and write administrator and user preferences.
Preference /Write
AR System User Preference Read These forms are used to read and write administrator and user preferences.
/Write


Type
AR System Version Control: Read These forms are used for Object Reservation feature.
Object Reservation /Write
AR System Version Control: Read These forms are used for Label Management.
Object Modification Log
Label /Write
Labeled Object /Write
AR System Currency Codes Read This form is used to get currency types that are shown in the Currency Types
property of a currency field.
AR System Orchestrator Read This form is used in Set Fields action when Data Source is set to
Configuration Webservice.
ReportType Read This form is used by Open Window action when Window Type is set to
Report.
Distributed Mapping Read These forms are used in Distributed Mapping and Distributed Pool editors
/Write
Distributed Pool Read These forms are used in Distributed Mapping and Distributed Pool editors.
/Write
DSO Distributed Logical Read Used by DSO Editors and DSO action to read logical names.
Name
BMC Remedy Localization Read This form is used by L10n Toolkit.

Toolkit: Items /Write
BMC Remedy Localization Read These forms are used by L10n Toolkit.
Toolkit: Location Package
Join
Toolkit: Location Package
Link
Toolkit: Locations /Write

Toolkit: Translations /Write

Toolkit: Translations Audit /Write
AR System Resource Read This form is used for localizing templates.

Definitions /Write
AR System Message Read This form is used for localizing messages.

Catalog /Write
AR System Currency Label Read This form is used to read localized current code.
Catalog

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 (see
page 2345). 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 (see page 2356).
Use the following procedures to create, modify, or delete BMC Remedy AR System roles:
To create and map roles (see page 1267)

To modify roles and role mappings (see page 1268)
To delete roles (see page 1268)

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
Name applications, but you must create a separate Roles form entry for each.
Role Name Name by which the role is known. Within each application, every role name should be unique. You can reuse the
same role name-role ID pairs across a suite of applications.
Role ID Integer ID that is the recognized identity of the role. The ID must be a negative number, such as -10001. Role IDs
must be unique for each application name. You can reuse the same role name-role ID pairs across a suite of
applications.
Test Enter or select one group name for the regular or computed group to which you want to map this role for the Test
application state. To enable this mapping, set the application's State property to Test. For more information, see
Working with deployable application states (see page 2356).
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 (see page 2356).
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.

4.
Note
- BMC Remedy AR System does not maintain the list of Application names. The
BMC Remedy AR System Administrator should keep a note of all the Application
names.
- Newly created roles appear in Permissions dialogs after the server recaches
(about 5 seconds, depending on your system).
To modify roles and role mappings
1. In a browser, open the Roles form in Search mode for the server that contains the
deployable application for which you are creating roles.
2. Search the form to retrieve a list of currently defined roles for a particular application.
3. Select the appropriate roles and modify information in the appropriate fields.
To delete roles
1. In a browser, open the Roles form in Search mode for the server that contains the
deployable application for which you are creating roles.
2. Search the form to retrieve a list of currently defined roles for a particular application.
3. Select the appropriate role.
A confirmation box appears to verify that you want to delete the role entry.
5. Click OK.
Administrator security role

BMC Remedy AR System provides administrators with interfaces to manage security policy and its
implementation in the AR System Administration Console, BMC Remedy Developer Studio, and
the BMC Remedy Mid Tier Configuration Tool. These clients allow the administrator to manage
server objects and system configuration settings, and to control access to AR System by human
users, BMC Remedy-based applications, and other external clients.
All user access definition and management is performed through forms that are accessible to
administrators. Policy management and implementation are controlled through the use of access
control groups and security role definitions and privileges. Access control groups are the basis by
which all user access is granted. Access control in AR System is additive. Each user starts out with
no access to AR System controlled objects, and administrators or subadministrators add
permissions as needed. Administrators can set default permissions and specific permissions on
objects in AR System, and subadministrators can set specific permissions to objects where
assigned.

Roles, including security roles, are specified in the AR System by membership in groups. The AR
System reserves eight group IDs for special group definitions with associated access privileges,
including the groups administrator and subadministrator. Members of the administrator group have
the security role administrator. Members of the subadministrator group have the security role
subadministrator.
Configuration of application servers, including application server passwords, is controlled by

administrators using the AR System Administration: Server Information form and other forms
accessible to the administrator through a browser. Many settings managed in the AR System
Administration: Server Information form are stored in the server configuration file (ar.cfg on
Windows or ar.conf on UNIX). The administrator must protect this and other configuration files
from tampering by setting the appropriate directory permissions and file settings. In addition to the
file protections assumed to be provided by the operational environment, application service
passwords stored in configuration files are obfuscated using a proprietary implementation of DES.
Access level options for administrators

In your application development and production environments, you can provide different levels of
access for administrators. The Overlay Group option on the Group Information Form, provides the
following access options:
Overlay Group field set to 1

When a group assigned to the user has the Overlay Group field set to 1, the user is
restricted to working on overlay and custom mode objects. In BMC Remedy Developer
Studio, the user can work only in Best Practice Customization mode.
When a group assigned to the user has the Overlay Group field set to 0, the user is
restricted to working on base mode objects. In BMC Remedy Developer Studio, the user
can work only in Base Developer mode.
When a group assigned to the user has the Overlay Group field set to 999999999, the
user is restricted from creating, modifying, deleting, and importing objects. The user can
only read and export objects from all layers.
Overlay Group set to (clear)
When the Overlay Group is set to (clear) the Group provides no restrictions on access to
base, overlay, or custom objects. For more information about Overlay Groups, see Creating
groups (see page 1255).
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 (see page 1276) and Operations on objects restricted by
development mode (see page 2342).

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 (see page 1261).
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 (see page 1272).
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 role (see page 1270)shows, create a group for each
collection of objects, for example, Engineering Subadministrators and Sales
Subadministrators.
Note
To give subadministrators access to an AR System server that has object

reservation enforced, you must grant them access to a form. See Version control
in BMC Remedy AR System (see page 2324).
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 (see page ).
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.
Access control
This section provides an overview of the BMC Remedy AR System access control. Topics include:
Additive access control (see page )

User and group access (see page )
Access to BMC Remedy AR System objects (see page )

Access to requests (see page )

Assigning permissions (see page )
Struct Admin group permissions (see page )
Note
For information about role-based access, see Role-based access overview (see page 93
).
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 (see page 90) for a description of user and group access
and Types of access control groups (see page 91) for a description of explicit and implicit groups.

Users in BMC Remedy AR System (see page 1276)

Groups in BMC Remedy AR System (see page 1276)
Special groups in BMC Remedy AR System (see page 1276)
Regular, computed, and dynamic groups (see page 1277)
Using a parent group for permissions inheritance (see page 1280)
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 (see page
).
Special groups in BMC Remedy AR System

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.
Special groups in BMC Remedy AR System
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.

Group ID Type Description
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 page ). See Enabling submitters to modify requests (see page 1308), 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 (see page 1292).
Sub 5 Explicit Provides administrative access to selected server objects. Subadministrators, members of this
Administrator group, can be granted administrative access to objects that have the Subadministrator
Permissions property. With administrative access, a subadministrator has the same access as
an administrator for that object. See Subadministrator security role (see page 1270). 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 Group field (field ID 112) for a request. A user automatically belongs to the Assignee Group
group for requests in which the Assignee Group field exists and contains the name or ID of a
group to which the user belongs, the name or ID of a role that maps to a group to which the
user belongs, or the user's name. For more information, see Assignee Group access (see
page 1293) and Form, active link guide, and application permissions (see page 1283).
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
(see to data or to administrative functions unless provided by other groups in the user's group list.
page
1277) Note: For more information about Struct Admin permissions, see Struct Admin group
permissions (see page 1261).
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
Subadmin (see Sub Administrator group members. If the object's Administrator group list contains a group in
page which the Struct Subadmin user is a member, the user has access. Struct Subadmin members
1277) 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.
* 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 (see page 1249).

Computed groups — Explicit groups that you create and to which users are assigned based
on the memberships of explicit groups included in an expression. For example, you can
create a computed group definition such as (A AND B) OR C AND NOT D. This computed
group includes the list of users who are members of both groups A and B, or members of
Computed groups make groups easier to manage. You can manage your users in a limited
number of regular groups, and use computed groups based on these regular groups for
more complex access control without the need to make changes in multiple groups.
Dynamic groups — Implicit groups are similar to the reserved Assignee Group group in that
the contents of special fields determine group membership. For more information, see
Dynamic group access (see page 1293).
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 (see page 93).
For information about assigning users to groups, see Adding and modifying user information
(see page 1249).
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 (see page 1293).
Here are access control group types:
Access control group types
Type Description Predefined groups Custom groups 2

of 1
access
control
group
Explicit A group to which you must assign users. Any regular and computed groups that you create.
Administrator Regular groups are groups to which you assign a
Sub specific list of users. Computedgroups are groups
Administrator to which users are assigned based on their
Customize memberships in groups included in an expression.

Type Description Predefined groups Custom groups 2

of 1
access
control
group
For example, you can create a computed group

definition such as (A AND B) OR C AND NOT D.
This computed group includes users who are
members of both groups A and B, or members of
Implicit A group to which a user automatically (or Any dynamic groups that you create.Dynamic
implicitly) belongs by virtue of the Public groups use the contents of special fields to
contents of certain fields in a request. Submitter determine group membership.
You cannot assign users to implicit Assignee
groups. All users are members of Public. Assignee
You use the other types of implicit groups Group
to control access to requests (row-level
database 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 (see page ).
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 (see page ).
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 (see page ).
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 (see page 1283)
Field permissions (see page 1284)
Active link permissions (see page 1289)

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 (see page 1304) and in the Field
permissions example (see page 1288). 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 (see page 2918).
Field permissions (see page 1284) 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 (see page 241).
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 (see page 115)
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 (see page
1302) and Assigning permissions for individual or multiple objects (see page 1305).
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 (see page 1302).
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.
active links in BMC Remedy AR System.
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 (see page 1291).
requests in BMC Remedy AR System.

Accessing requests
Controlling access by using implicit groups--Row-level security (see page 1291)

Submitter and Assignee access (see page 1292)
Assignee Group access (see page 1293)
Dynamic group access (see page 1293)
Using the Request ID field with implicit groups (see page 1293)
Using the Assignee Group and dynamic groups--Examples (see page 1295)
Controlling access to requests for hierarchical groups (see page 1299)
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 7 None 112 No User, group, or role

Group names
Dynamic 60000- None 60000- No User, group, or role

groups 60999 60999 names
You can also grant parent groups row-level access. For information, see Controlling access to
requests for hierarchical groups (see page ).
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 (see page
).
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 (see page
).
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 (see
page 1299).
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 (see page 255).
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.
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

5.
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 (see page 1294).
For more information about all settings in the BMC Remedy AR System Administration:
Server Information form, see Configuring AR System servers (see page 255).
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 (see page 2720).
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 (see page 1294).
For more information about all settings in the BMC Remedy AR System Administration:
Server Information form, see Configuring AR System servers (see page 255).
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

Hierarchical groups have two new configuration parameters. For details on configuring these
parameters, see Configuration settings E-M (see page 1207). The following table describes these
parameters:
Name
Allows you to configure the number of threads (default value is 1) that will be used for computation of hierarchical groups. When
hgthreads
all the existing worker threads are in use, the system starts additional threads as needed until the configured number of threads is
reached. These additional threads remain active until the BMC Remedy AR System server is rebooted. BMC recommends that
you use a significantly high number of threads (at least 5) in the following scenarios:
When changes are made to the group hierarchy

When group changes are applied to forms
You must increase the number of threads because these changes could result in updates to numerous entries across several
forms.

Name
Allows you to configure compute delay (in minutes) for hierarchical groups. The default value for this delay is 5 minutes. The BMC
hgdelay
Remedy AR System server waits for the specified amount of time before hierarchical groups begin the compute activity. The delay
time is calculated from the time when the last change is made to the group hierarchy and when group changes are applied to the
forms. If during the delay period a new change is made, then the delay time is reset to take into account the last change made.
The following example will help you understand the hgdelay concept:
Suppose you have configured hgdelay time as 10 minutes. The BMC Remedy AR System server waits for 10 minutes before it
computes the worker threads. During the delay time, if you make certain changes at the 7th minute, then the delay time is further
extended by 10 minutes. Thus the BMC Remedy AR System server begins its task of computing worker threads at the 17th
minute. If you make any subsequent changes, the delay time is extended by 10 minutes each time.
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. (You can also set static permissions inheritance property 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 BMC Remedy AR
System populates 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, BMC Remedy AR System checks for defined ancestor groups. If any
exist, BMC Remedy AR System enters the parent group ID (or IDs for 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 (see page ).
To control access to requests for hierarchical groups
1. Follow the appropriate procedure in Using the Assignee Group and dynamic groups--
Examples (see page ) to configure row-level access for the child group.
2. Create a new dynamic group that identifies 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.
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 the following example:
112:60002 60001:60002
Enter the child dynamic group ID first, followed by a colon, and then the parent group ID.
For detailed information on permissions inheritance, see Using a parent group for
permissions inheritance (see page 1280).
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 (see page ).
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 (see
page ) and To assign permissions for other objects (see page ).
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 (see page ).
Batch permissions — You can specify permissions for multiple objects of the same type at
the same time. For more information, see Modifying object properties (see page 2277).

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 (see page ).
Defining default permissions (see page 1302)

Assigning permissions for individual or multiple objects (see page 1305)
Checking object visibility for the Public group (see page 1308)
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 (see page )

Field permissions (see page )
Active link permissions (see page )
Assigning permissions for individual or multiple BMC Remedy AR System objects (see page
)
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.
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 Access for users in the group or groups mapped to
level the role
Active link guide, application, form, web Visible View and access the object in the user client.
service
Active link guide, application, form, web Hidden Access to the object only through workflow.
service
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 (see page 1306)

To assign permissions for other objects (see page 1306)
To assign permissions for one or more fields (see page 1307)
To assign permissions for a group to multiple objects (see page 1307)

To assign permissions for forms
1. In Developer Studio, open the form for modification.

3. Expand the Permissions panel, and then open the Group Permissions subpanel.
4. In the Group Permissions subpanel, use the arrow buttons to move the appropriate groups
and roles into the Permissions list.
5. For each group or role in the Permissions list, click the drop-down menu in the Permissions
column to set the access level to Visible or Hidden.
6. To configure hierarchical group access to the form, select Static Permissions Inheritance.
When static permissions inheritance is allowed, the Complete Permissions area shows a list
of all groups that have access to the form, including any parent groups. However, you must
save the permissions changes and reopen the Permissions panel and Group Permissions
subpanel on the Definitions tab to see the current list.
Note
You will not automatically see updates to this list if changes are made
simultaneously by another developer. To see concurrent updates, you must close
and reopen the Permissions panel on the Definitions tab.
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 (see page 3031).
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 (see page 1302).
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 (see page 3031).
4. Click Set Permissions.
5. In the Permissions dialog box, use the arrow buttons to move the appropriate groups and
roles into the Permissions list.
All groups defined on the server (or roles defined for the application that contains the object)
are displayed.
The Submitter, Assignee, and Assignee Group groups are implicit based on field contents.
For more information about implicit groups, see Controlling access by using implicit groups--
Row-level security (see page 1291).
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 (see page 1302).
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.

9.
Note
To assign common permissions to a collection of objects, see Modifying object

properties (see page 2277).
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:
Validating password information (see page 1309)

Enforcing a password policy introduction (see page 1310)
Setting up the mid tier for the password policy (see page 1312)
Forcing users to change their passwords (see page 1312)
Refer to Multitiered access control model (see page 94) 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 (see page 1249)
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 (see page 282).
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 (see page )
and Enforcing restrictions on passwords (see page )). 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 (see page 291). 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 (see page ).

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 (see page 1325). For
information about the Cross-Reference Blank Password feature used with external
authentication, see Cross-referencing blank passwords (see page 831).
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 (see page 1313)

Forcing new users to change their passwords (see page 1314)
Forcing individual users to change their passwords (see page 1315)
Enforcing restrictions on passwords (see page 1316)
Setting security options using Server information form settings (see page 1321)
Disabling password management for individual users (see page 1325)

Reverting an individual user to global password management settings (see page 1326)
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.
(Click on the image to expand it.)
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 (see page )
Setting up password expiration with scheduled warnings (see page )
Disabling an account after the expiration period (see page )
4.
4. Click Save.
All users are forced to change their passwords at their scheduled expiration date. When
users change their passwords, they must enter the old password once and the new
password twice.
Forcing new users to change their passwords

To force new users to change their passwords:
Password Management Configuration.
2. In the User Password Management Configuration form, select the New User Must Change
Password check box.
3. Click Save. Now, when you create a user, the user is prompted to change the password the
first time the user 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.
2. Search the appropriate user.

3. Modify the Password Management fields for the user, as needed. For more information
about the User form, see Adding and modifying user information (see page 1249).
4. Select the Force Password Change on Login check box.
5. 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 (see page 1326). 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 (see page 1316)

Restriction qualifications scenarios (see page 1318)
Setting up password expiration with scheduled warnings (see page 1319)
Disabling an account after the expiration period (see page 1320)
Enabling users to change their passwords at will (see page 1320)
Restricting the use of certain characters in passwords

On UNIX, users must enter two backslashes (\ ) in front of any dollar signs ($) in their passwords.
For example, if a user's password is testBMC$12, the user must enter it as follows: testBMC \ \ $12
.
To avoid login problems, restrict the use of $ in passwords.

Setting up password restrictions
Password Management Configuration. The User Password Management Configuration
form appears.
2. To disable the default HIPAA character restrictions, select the Disable Default Character
Restrictions check box.
This check box disables the default HIPAA character restrictions regarding non-
alphanumeric characters and case-sensitivity. If the check box is selected, users can
enter any characters in the Password field, except for characters that are restricted
according to what you enter in the Restrictions Qualifier field.
Length restrictions are still enforced, but you change them in the Minimum Length
field as described in the following step.
3. Complete the following fields in the Restrictions section.
Minimum Length — Sets the minimum length the user must enter when changing a
password. You can enter a length of 1 through 30; the default is 8.

3.
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 (see page ).
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
form appears.
2. Complete the following fields in the Enforcement Policy section.
Number of Days Before Expiration — Indicates the numbers of days before a user's
password expires if it is not changed.
Number of Warning Days — Indicates when a user receives a warning message
before the password is set to expire unless changed.
3. Click Save.
Note

3.
You can perform this function in the User form for individual users. See Adding
and modifying user information (see page 1249).
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:
form appears.
2. In the Days After Expiration Until Disablement field, enter the number of days after which
a user's account is disabled if the password is not changed.
3. Click Save. You can also perform this function in the User form for individual users. See
Adding and modifying user information (see page 1249).
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.
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 page 1065)).
To set advanced options
Server Information. The AR System Administration: Server Information form appears.
AR System Administration: Server Information form — Advanced tab
3. Edit the options listed in the following table as needed, and click Apply.
Default Web Specifies the base URL for the mid tier and is used by clients such as Flashboards.
Path The URL appears as:
http: //hostName/contextPath
hostName is the name of the server (for example, eng.remedy.com).

contextPath is the URL context path of the AR System application registered with the
servlet engine. This is set up during installation. The default value is arsys. If your
company has multiple domains, use a fully qualified path name.

Maximum For forms that contain hierarchical data, such as manager and employee relationships,
Depth for specifies the maximum number of levels in the hierarchy that a recursive query
Hierarchical retrieves. By default, the maximum is 25. Enter any integer greater than 0. See
Query ARGetListEntryWithMultiSchemaFields (see page 3848).
Maximum Specifies the maximum number of temporary tables that can exist on an AR System
Vendor server for a single vendor form. The ARGetListEntryWithMultiSchemaFields function
Temp Tables 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
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
Line Length single line of the message is over this length, a return is automatically inserted. Limits
in Email the line length of email messages passed 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
Notification Default Web Path is used. (The Email Notifications Web Path field is available
Web Path because the Default Web Path is specified for other applications like Flashboards,
and it might be different from the mid tier web path for opening requests in a
notification.) If your company has multiple domains, use a fully qualified path name.
Security Active Link Specifies the only directory that the Run Process active link action can run from, for
Run example, C:\arsys. If no directory is specified, active link processes can run from any
Process directory.
Directory
Active Link Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no
Run path is specified, administrators can specify any shell.
Process
Shell(UNIX
servers
only)
Allow Enables the administrator to use the arcache and arreload utilities. See arcache.exe or
arcache and arcache (see page 1136) and arreload.exe or arreload (see page 1139). The option is
arreload selected by default.
Client Maximum Specifies the maximum number of concurrent client-managed transactions. The default
Managed Concurrent is 10, and the 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 timeout occurs. The default is 60 seconds, and there is no maximum. If a timeout
occurs, the server automatically rolls the transaction back, and the client receives an
error on the next operation that uses the transaction handle.
Localized Localize Enables the administrator to enable or disable localization of the server. Selected
Error Server indicates that the server is localized and enabled for such tasks as searching entries in
Messages localized forms, or using AR System Message Catalog to load the message. Clients

are enabled to display localized messages, but clients still have local catalogs, such as
the user.dll. You must select the Localize Server check box to see localized error
messages. Cleared is the default and indicates that the server is not localized. Such
tasks as searching localized forms and the localization of messages are disabled. The
server does not use the AR System Message Catalog form, and messages are shown
from the error catalog. The default message is displayed.
Note: If users in a different locale open a form with localized views before you select
this option, you must flush the mid tier cache after setting this option to make the
localized view available on the web. See Configuring the Cache Settings page (see
page 440).
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 (see page 1093).
Catalog Displays the name of the form the server uses to resolve error messages when
Form Name "Localize Server" is selected. For more information about the AR System Message
Catalog form, see Localizing messages manually (see page 3192).
Filters Maximum Specifies the number of filters that can be performed in an operation. The default and
Filters for recommended number is 10000. Increase this number at your own risk only if you
an Operation reach a limit in your system and you have verified that your workflow is valid.
Maximum Specifies the maximum number of nested filters and filter guides that execute to
Stack of prevent recursive actions on the server. The default and recommended number is 25.
Filters Increase this number at your own risk only if you reach a limit in your system and you
have verified that your workflow is valid.
Server Server Specifies how the server records server statistics. Select one of the following options:
Statistics Recording Off, the default, do not record server statistics; Cumulative Queue, record a cumulative
Mode statistic that is a combination of all the queue statistics; and Cumulative and Individual
Queue, record a cumulative statistic that is a combination of all the queue statistics as
well as statistics of each queue individually. Information is recorded in the Server
Statistics form, which is installed when you install AR System. See Server statistics for
baseline data (see page 1321).
Recording Specifies how often the server records server statistics. The default is 60 seconds.
Interval Remember that one (Cumulative Queue) or more (Cumulative and Individual Queue)
(seconds) entries are recorded in the Server Statistics form during each interval. If you have a
short interval, many records are created. This can affect the performance of the
system and the size of the database if you configure with too short an interval.
Server Group Server If the server belongs to a server group, specifies the name of the group. All servers in
Group the server group share this setting.
Names
Check Specifies how often the server communicates with other servers in the group. Each
Interval server can register its own status, determine whether any server is delinquent,
establish the parameters needed for sending signals, and determine operational
responsibilities. The default value is 60 seconds, the minimum is 30 seconds, and
there is no maximum. All servers in the server group share this setting, and when it is
changed, all the AR System servers in the group must be restarted.
Preference Preference Specifies where user preferences are read from. The options are User Defined, where
Server Server users can choose 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, 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 (see page 1346).
Preload Preload If the number of preload threads is not zero, specifies whether the threads are used
Tables Tables At only at server startup or for all cache reloads from the database. See Setting the
Configuration Init Only Preload Tables Configuration option (see page 369). The values are 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 (see page 1105).
Number of Specifies the number of preload threads used when information is loaded from the
Preload database into the server cache. The maximum value is 30 or twice the number of
Threads preload segments, whichever is lower. The server might reduce the number of threads
at runtime if it determines that threads would be started with no work to do. If this field
is set to 0, the Preload Tables Configuration option is off. For information about the
corresponding configuration file setting, see "Num-Preload-Threads" in ar.cfg or ar.
conf options N-R (see page 1105).
Number of Specifies the total number of preload segments handled by the preload threads. Vary
Preload this setting to balance the load between preload threads and to optimize cache load
Segments time. A good initial setting for this option is 1/3 the number of schemas (forms) in the
AR System server. See Setting the Preload Tables Configuration option (see page 369)
. For information about the corresponding configuration file setting, see "Num-Preload-
Schema-Segments" in ar.cfg or ar.conf options N-R (see page 1105).
Disabling password management for individual users

To disable password management for individual users:
Users / Groups / Roles > Users. The User form opens in Search mode.


3. Select the Disable Password Management For This User check box.
4. Click Save.
Reverting an individual user to global password management settings

To revert an individual user to global password management settings:
Users / Groups / Roles > User. The User form opens in Search mode.


3. Clear all the Password Management fields on the form.
4. Click Save.
Enabling skins administration for users

You can enable any user to configure and modify skins on the form views using the Skin Designer
role in BMC Remedy AR System. In a multi-tenant environment, you may enable tenants to
configure skins for their environment. By default, these tenants do not have the permissions to
configure skins. You can enable this feature by mapping Skin Designer role to specific tenant
groups.
Note
When the tenant applies skins, the skins will be applied to that server's forms and is
limited to that tenant environment. In a mid tier multi-tenant environment, it affects only
the tenant using that server.
To enable skins configuration for users
1. Create a AR System access control group using the BMC Remedy Mid Tier. Use the Group
form to create the group to which you want to grant access for configuring AR System skins.
For example, you might want to create a group with a name such as AR System Skin
Administrator. For more information about creating a group, see Creating groups (see
page 1255).

Note
You can also use an existing group for mapping the Skin Designer role.
2. Open the Roles form in New mode and create a new role for the following applications:
a. AR System Administration
b. AR System Skins
3. For each application, enter the following details:
Field Value
Application Name AR System Administration AR System Skins
Role Name Skin Designer Skin Designer
ID -2 -2
Mapped Group Test: AR System Skin Administrator Test: AR System Skin Administrator
Production: AR System Skin Production: AR System Skin
Administrator Administrator
For more information about creating and mapping roles, see Creating and mapping roles
(see page 1266).
Note
If the Skin Designer role is already defined for the above applications, modify the role to
add group information by searching the Roles form in Search mode.
When you map the role to the AR System Administrator group, all the users of the group can
access the AR System Skin Administration console. In a browser, the user can access the skin
administration console by clicking AR System Administration > AR System Skin Administration
. For more information about defining skins, see Defining skins (see page 3150) and Applying skins
to form views (see page 3144).
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 (see page 1329)

Authentication String Alias introduction (see page 1330)

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 30
Length
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 (see page 831)).
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:
Name Authentication String
Field ID 118
Data Type Character

Database 255
Length
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 (see page 831) 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.
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.
Defining your user base

This section provides instructions for managing information about your BMC Remedy AR System
users. Topics include:
User licenses (see page 1333)

User form access (see page 1338)
See the following sections for related information:
Viewing user license information (see page )

Enabling submitters to modify requests (see page )
Setting up an authentication alias (see page )
User licenses
When creating users, you must assign a license type to each user. The type of license a user has
determines the user's ability to access BMC Remedy AR System objects and to perform tasks.
This section contains the following information to assist you with licensing:
License types for users to access BMC Remedy AR System server (see page 1333)
About floating licenses in a license pool (see page 1335)
Releasing floating licenses to a license pool (see page 1335)
Viewing user license information (see page 1336)
For more licensing information, see License overview (see page 85) and Working with BMC
Remedy AR System licenses (see page 243).
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 (see page 1308).
Restricted
Read

License Description
type
Enables users to create, search for, and display requests within their assigned permissions. Users with Restricted
Read licenses cannot modify any requests, including their own.
Restricted Read licenses enable the same login account to access BMC Remedy AR System from multiple IP
addresses simultaneously.
You can give guest users a Restricted Read license. See Setting administrative options (see page 291).
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 (see page 1335).
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 (see page 85) and Working with BMC
Remedy AR System licenses (see page 243).
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 (see page 291). 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 (see page 1249
) and Groups in BMC Remedy AR System (see page 1276).
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.

A user closes the browser window.
If a user closes the browser window, which is displaying BMC Remedy Mid Tier, then the
system performs an automatic logout after a short delay. For more information about
session timeouts, see the License Release Timeout 30 -300 Seconds row in the General
Settings parameters table in the Configuring the General Settings page (see page 431)
section.
Note
If the user is accessing BMC Remedy Mid Tier on multiple browser windows, the
token is released only after the user closes the last browser window associated
with the current HTTP session or navigates away from BMC Remedy Mid Tier.

A user does not perform a BMC Remedy AR System operation for the period of time in the
floating license time-out interval. See the Floating License Timeout (hours) row in the
Timeout tab fields table on the Setting timeout options (see page 265) section.
If a timeout occurs in a BMC Remedy Mid Tier session, all the floating licenses
held by the user are released back to the pool.
In addition, administrators can manually release user's license one time in a 24-hour period by
using the following procedure.
To release a floating license
> Application > Users/Groups/Roles > License Review.
2. From the Category list in the Manage User Licenses form, select Current Licenses.
3. From the License Type list, select Floating. A list of users with the selected license type
appears.
4. From the list of active users, select the appropriate user.
5. Click Release User. The license held by that user is released. Another user can take the
license and start working. If the original user returns, the user cannot get back into the
system if no licenses are available.
Note
If you release a Fixed or Read license, this procedure removes the user from the
list of current users; it does not affect the user's ability to connect to the server.
The next time the user accesses the server, the user obtains the licenses again
and 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 (see page 1249).

To display user license information
> Application > Users/Groups/Roles > License Review. The Manage User Licenses form
appears.
License information
2. From the Users Category list, select one of these options:

Server - Current Users — Displays the following information for each user
connected to AR System through a BMC Remedy AR System license:
Name of the user
Type of AR System license assigned
Connect time during the current session
Time that the user last accessed the server during this session
Floating license pool
Server - Registered Users — Displays the following information for all users known
to BMC Remedy AR System with an AR System license:
Name of the user
Default notification mechanism
Email address
Note

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 (see page 4100).
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 (see page ).
Understanding database security issues

In general, BMC Remedy AR System hides the underlying database from the user. The BMC
Remedy AR System (AR System) server interacts with the database and provides information to
the user independent of the underlying database. All access through the API supplied with the
product goes through this server and is independent of the database. This section contains topics
related to database security:
Using IBM DB2 Universal Database user names and passwords (see page 1339)
Assigning permissions when using SQL queries (see page 1341)
For information about configuration options and parameters associated with specific databases,
see Configuring after installation (see page 241).
Using IBM DB2 Universal Database user names and passwords

IBM DB2 Universal Database user name and password behavior that you need to consider
include:
When the DB2 database resides on the same computer as the BMC Remedy AR System
(AR System) server, ARAdmin user is not used. You can run the AR System server
installer as root or any other user as long as that user has administrator privileges for the
specific DB2 instance on which you install the BMC Remedy AR System database.
When the DB2 database resides on a different computer from the AR System server, the
database user name, aradmin, must be created in lowercase before installing AR System
server. The database user name is associated with the operating system. For overwrite and
new installations (but not for upgrade installations), this operating system account must exist
before installing AR System server. The password must be AR#Admin#. After the AR
System server is installed, you can change the password.
Because the database user name is associated with the operating system, you must make
password changes in the operating system and set the new password in the AR System
Administration: Server Information form. For more information about this form, see
See Using IBM DB2 Universal Database with BMC Remedy AR System (see page 2032) 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 System Administration: AR System Configuration
Generic UI form.
a. In the AR System Administration: AR System Configuration Generic UI form,
from the Component Name list, select the appropriate component.
b. From the settings table, select the Db-user setting.
c. Change the Db-user value to match the value you specified in step 2, and click Apply
.
d. Click Close.
To change the BMC Remedy AR System database password
Use the Database tab in the AR System Administration: Server Information form. See
OR
Use the ARSetServerInfo API call. See ARSetServerInfo (see page 4039).
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 (see page 2032) 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 ARAdmin

Server
Oracle ARAdmin
Sybase ARAdmin
If you run BMC Remedy AR System as one of these users without permission to access the
database, you cannot issue the SQL query.
To access non-BMC Remedy AR System databases, use the database name as part of the SQL
query syntax. For example, for a Sybase or Microsoft SQL Server database:
databaseName.owner.table
acme.ARAdmin.CUSTMR_INFO
Using audit records

This section describes the various types of log files, also called audit records, available in BMC
Remedy AR System (AR System). It also shows how you can trace the activity of most AR System
server functions using audit records.
Viewing BMC Remedy AR System Server audit records (see page )

Viewing BMC Remedy Mid Tier audit records (see page )
Viewing BMC Remedy Distributed Server Option audit records (see page )
Viewing database audit records (see page )
See Troubleshooting (see page 4270) 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 (see page 4385) 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 Click to view the log file.

File
See BMC Remedy Mid Tier logging (see page 4316) 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 Description
Remedy
Distributed
Server
Option log
file
ardist.log Contains information about the DSO server.
ardist. Contains information about the default distributed pool.

default.log
ardist. Contains information about a custom distributed pool. Windows log file names In a Windows environment, if the
poolName. name of a distributed pool contains special characters, BMC Remedy AR System replaces those characters with a
log 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

BMC Description
Remedy
Distributed
Server
Option log
file
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 (see
page 4335).)
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 (see
page 4385). 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.
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.
Accessing preference forms for centralized preferences (see page 1345)

Restricting preferences from users (see page 1345)
Configuring clients to use a preference server (see page 1345)
Establishing a mandatory preference server (see page 1346)
Behaviors associated with preference server configuration (see page 1347)
Setting the AR System User Preference form (see page 1348)
Setting user preferences in the BMC Remedy Mid Tier (see page 1373)

Accessing preference forms for centralized preferences

Centralized preferences are saved on a preference server. Preference servers contain the
following preference forms, which are installed when you install the BMC Remedy AR System
server.
Preference forms
Form Purpose and Content
AR System Stores preferences for web clients. Administrators can set the value of the fields in the AR System User
User Preference form (see page 1348)by using the PERFORM-ACTION-SET-PREFERENCE Run Process command
Preference (see page 2871).
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 (see page 2996)
form Security administration (see page )
AR System Stores preferences for BMC Remedy Developer Studio and BMC Remedy Data Import. By default, this form
Administrator has administrator permissions only. You might want to define subadministrator permissions (see page 1272).
Preference Display preferences and the list of login servers are stored in the AR System User Preference form. Developer
form Studio and Data Import users can also access these preference settings in the Options dialog box (choose
Window > 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.
In BMC Remedy User Tool, 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 (see page 3403).
Restricting preferences from users

To restrict preferences, remove Public permissions from individual fields in the AR System User
Preference form (see page 1348).
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 (see page 436).

Establishing a mandatory preference server
Note
This topic is applicable only for BMC Remdey User Tool.
As a BMC Remedy AR System administrator, you can designate a mandatory preference server
that stores the system preference information. This configurable server setting provides a
mechanism to enforce the use of centralized preferences across an organization.
To enable a mandatory preference server
Server Information.
Server Information — Advanced tab

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 (see page ).
4. Click OK.
Behaviors associated with preference server configuration

Different behaviors occur depending on the server settings you configure for the Preference Server
Option on the Advanced tab of the AR System Administration: Server Information form.
"User Defined" behaviors
User action Behavior
Leaves the Preference The local preferences are used (ar.ini file).
Server field blank
Specifies a valid preference The system connects to the preference server, and the Accounts list is updated to reflect the list of
server servers specified on the Server List setting.
Specifies an invalid The local preferences are used (ar.ini file).

preference 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
Preference name is written to the Preference Server field of the Login dialog box. In addition, the accounts list is updated to
Server field reflect the list of servers specified on 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
valid specified on the Server 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
invalid name is written to the Preference Server field of the Login dialog box. In addition, the accounts list is updated to
preference reflect the list of servers specified on 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.
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 (see page 1348)

Setting the Accessibility tab (see page 1349)
Setting the Advanced tab (see page 1351)
Setting the Alert tab (see page 1352)
Setting the Confirmation tab (see page 1354)
Setting the Edit tab (see page 1355)
Setting the General tab (see page 1357)
Setting the Home Page tab (see page 1359)
Setting the Locale tab (see page 1360)
Setting the Logging tab (see page 1361)
Setting the Misc tab (see page 1363)
Setting the Recent tab (see page 1365)
Setting the Report tab (see page 1365)
Setting the Web tab (see page 1367)
Setting the Window tab (see page 1368)
Date and time formats (see page 1369)
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
Name entering that user's login name in this field. Users can search for and modify their own preference records. The
default setting is $USER$.
Short Lets the administrator create, search for, and modify preferences based on a value in this field. The default setting
Description is Preference entry 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 Legacy*
Message options are
No Action — No messages are shown for accessibility. Active link message

actions of the type Accessible are ignored.
Message Action — Displays accessibility messages defined by the active link
message action of type Accessible.
All Actions — Displays accessibility messages to reflect visual changes on the
page as well as accessible messages defined by an active link message action
of the type Accessible.
Accessibility messages are displayed for visual changes caused by Change Field and
Set Field active link actions, and other user actions such as table refresh. These
messages reflect the visual changes that the user would have experienced otherwise. If
a field is hidden, changes caused by these actions are ignored.
Note: These options are not used in the BMC Remedy Mid Tier 6.3 and later.
* Legacy = The field is available for legacy environments that use BMC Remedy User, which is no
longer shipped with BMC Remedy AR System.

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 (see page ).
Setting the Advanced tab

AR System User Preference form — Advanced tab
Advanced tab fields
Area Field Name Description Client

name
Form Default Specifies the view to be used as the default for all forms. Legacy*
Form 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
Note: If the user enters an extension that does not exist, BMC Remedy AR System
View
determines which view best fits. This might not be the default view.
Extension
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 sub
administrator to an active server.


name
Table Refresh Specifies whether the data in a table field is refreshed automatically every time a form is Web
Fields Content on displayed.
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: Legacy*
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. Legacy*
Underscores Using underscores is 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 Legacy*
View specify a value in this field.
Sort Criteria Displays the value set when the user chooses Actions > Sort Options and specify Legacy*
values. The user can set sort 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 Designates whether logging should occur for Alert. N/A*
Logging
If Yes, Logging Designates the path and name of the log file. By default, alert log files are stored N/A*
Path with a .log file extension.
Open Alert List Designates which application should be used to open the Alert List. The options Web
using are
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 Designates the process to run if the previous option is set to Yes. N/A*
File
* 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 Web
Request are
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 Defines whether a confirmation appears when the user tries to delete a report. Legacy*
Report The options are
No — (Default) The report is deleted without verification.

Yes — A dialog box appears when the user tries to delete a report.
When Deleting a Defines whether a confirmation appears when the user tries to delete a saved Legacy*
Saved Search search. The options are
No — (Default) The saved search is deleted without verification.

Yes — A dialog box appears when the user tries to delete a saved
search.
When Deleting a Defines whether a confirmation appears when the user tries to delete a macro. Legacy*
Macro The options are
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 Legacy*
Field Column changes the size of columns in the table field, including the server name, form name,
Width table field ID, column ID, and the size of the column.
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 Legacy*
Width changes the column size in a results list.
Column Information about a results list that BMC Remedy AR System saves when the user Legacy*
Order reorders the columns in a results list.
Grid Height Parameter set in Customize View mode by choosing Layout > Grid Size and specifying Legacy*
a value.
Grid Width Parameter set in Customize View mode by choosing Layout > Grid Size and specifying Legacy*
a value.


name
App Flag that specifies whether to display extra field name and ID information in the field Legacy*
Development Help text. Values are:
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 Legacy*
Base Menu menus.
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 Web
Threshold to list menus.
Level When smart menus is selected, the number of levels where menus change from pop-up Web
Threshold to list menus.
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
Setting the General tab

AR System User Preference form — General tab
AR System User Preference form — General tab

name
Search Search Path Designates the directories where the user can access custom reports and macros. The path Legacy*
is typically userHomeDirectory/arHome/arcmds. To change the search path, the user
must enter the entire directory name for the directory to which the user wants access. To
specify more than one directory, the user must separate each directory name with a
semicolon.
Note: If the user deletes all directories from the search path, the user cannot access any
custom reports or macros.
Num Items The number of recently used items. The user can specify from 4 to 9 items. The default is 5. Legacy*
in Recently This setting applies to 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
Specifies the amount of time (in milliseconds) that the system waits to display a tool tip after Web
the user hovers over an object.


name
Tooltip Hover Wait

Hover Time in
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, Web
Search displays the records in 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 Defines whether the user views only the results list after every search. If the user selects No Web
Result List , the results list and a detail pane are displayed after every search.
Only
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
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 Web
Window only a portion of the 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.
Display As Specifies how menus attached to a character field are displayed. The options are: Web


name
Field Default — See Popup menus.

Menu 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 (see page ). 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 Web
Page Server Configuring home page preferences (see page 3176).
Form Designates the name of the form to be used as the default home page when the user logs in. For Web
Name more information, see Configuring home page preferences (see page 3176).
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 User Designates the language displayed on the user's system, in the format language _country, Web
Locale where language is the language code (such as fr for French or en for English), and country is
the two-letter country code (such as FR for France or US for United States). Some sample
entries are:
en_US — English (United States)


name Name
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 Web
Zone example, Asia/Tokyo, 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 Legacy*
Date are:
/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 Legacy*
Date from the Display Date/Time Style menu list. To customize separators and other options, the
/Time user must use a predefined Windows format or a customized Windows format. The EEE and
Format EEEE day formats do not work in this field. For example, if the user enters EEEE, MMMM dd,
yyyy, the day of the week displays in the browser as EEEE, not the actual day (for example,
Tuesday). This field is clear by default.
Currency The type of currency to be applied for this locale (for example, USD for United States dollars). If Web
currency is specified here, it overrides the developer-defined Initial Currency Type field
property. If this field has a default value, it overrides the User Preference and the Initial
Currency Type.
Setting the Logging tab

AR System User Preference form — Logging tab

Logging tab fields

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. Mid tier
Timings (Web) Designates whether the time of a request and responses between browser, mid tier Mid tier
server, and BMC Remedy AR System server are logged.
Server API Designates whether use of APIs on the server is logged. Mid tier
Filter Designates whether use of filters on the server is logged. Mid tier
Database Designates whether activity on the database is logged. Mid tier
Global Global For future use.

Logging
Enabled
Log File Path Defines the path to the log file. Mid tier
For more information about logging, see Analyzing logs (see page 4373) and Tracking client caches
(see page 4298).
After you enable logging, the information log appears on the Workflow Logging window. If
you want to delete the generated logs, click the Clear button that is displayed at the top
of the Workflow Logging window.

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 Legacy*
user selects an item from the Open Object List and right-clicks to create a shortcut or
when the user right-clicks a results list and chooses Send To > Desktop.
Find Not currently used. Legacy*
Performance Preferences that relate to how the browser caches forms. Definitions (for forms and Legacy*
related workflow) are loaded into memory from the .arf and .arv cache files and
retained as long as these files are current. This enables subsequent loads of the same
form to load more rapidly since the definitions do not have to be re-read from the disk
each time. To reduce the amount of memory used, several checks are made
periodically to see if definitions can be removed from the memory cache. During these
checks, the following calculation is performed:
Duration Since Last Used = Current Time - Time Definition Last Used
Max Age In If the Duration Since Last Used value is greater than the preference set for Max Age Legacy*
Minutes In Minutes, the form 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 Legacy*
Minutes In Minutes, the form definition can be removed from the memory cache. If the system
is approaching the memory limit (Percent of Memory), the Duration Since Last Used
value is taken in conjunction with the Min Age In Minutes value to determine whether
the definition can be removed from the memory cache.
Usage Each time a form is opened, the system increments a usage count. As the memory Legacy*
Threshold limit is approached, the Usage Threshold value is compared to the usage count to
determine if the definition can be removed from the memory cache.
Legacy*

Percent Of Represents a memory threshold. It is compared to the percent of memory used for the
Memory memory cache to 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 RPC Timeout for submits in the browser. Legacy*

Timeout
Normal
RPC RPC Timeout Long queries in the browser. Legacy*

Timeout
Long
RPC RPC Timeout for extra long operation in the browser. Legacy*
Timeout
Extra Long
View Show Designates whether the macro bar is displayed when the browser starts. Legacy*
Macro Bar
Show Designates whether the status bar is displayed when the browser starts. Legacy*
Status Bar
Show Designates whether the toolbar is displayed when the browser starts. Legacy*
Toolbar
Disable Designates whether items under BMC Remedy on the Web under the main Help Legacy*
Web Help menu in the browser are disabled.
Save Designates whether to save information about open New and Search windows in the Legacy*
Window On browser when you close the tool.
Close
Query On Designates whether you can initiate a query by pressing the Enter key in the Request Legacy*
Return ID field.
Close After Designates whether to close a New window after a request is submitted in the Legacy*
Submit browser.
Show Lang Obsolete. Legacy*

DLL Not
found
Step Size Obsolete. Legacy*
Result Designates which panes open when you double-click a record in a results view. The Legacy*
Open On options are:
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 Legacy*
browser.
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 Margin Defines the number of blank characters from the left or right edge of the page. The Web
Margins default for the left and right margin is 0 characters.
Right Margin
Top Margin Defines the number of blank lines from the top or bottom edge of the page. The Web
default value for the top and bottom margin is 1 line.
Bottom Margin
Default Column Titles Defines the default characters to separate column titles, columns, or requests, Web
Separators respectively. By default, column titles are separated by hyphens (-), and columns and
Column requests are separated by a blank space. You can use any of these special
characters:
Request
\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 Web
default page page size.
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 Web
Default Per are:
6 — Column titles appear for each request in the report.

7 — Column titles appear for each page in the report.
8 — No default.


name
Page Break Per Designates a default value for how often page breaks occur in a report. The options Web
are:
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 N/A*
names. The options are:
No — (Default) Do not replace the dot.

Yes — Replace the dot.
* N/A = The setting does not apply to the web client. The setting applies to activities such as
Setting the Web tab

AR System User Preference form — Web tab
Web tab fields

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


name Name
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 Web
Interval default value is 0. The 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 Web
Servers the server names to retrieve alerts from this field. The server names must be separated by the
comma ( , ) delimiter. This field is clear by default.
Date Display Specifies the format in which the date and time appear. Options are Web
/Time Date
Text /Time Short
Style Long
(Web) Custom
The formats adhere to the ICU (International Component for Unicode) format. The format is
platform-independent and is not automatically the same as preferences set in the browser, or
as any preferences set in the Windows Control Panel. The user must use a predefined ICU
format or customize an ICU format to set web view Date/Time appearances. The default is
Short.
Custom Specifies the format of date strings to be displayed in the browser if the user selects Custom Web
Date from the Display Date/Time Style (Web) menu. The user can add a forward slash (/), dash (-)
Format or a period (.) as separators. This field is clear by default. For more information about date
formats, see AR System server components and external utilities. (see page )
Custom Specifies the format of time strings to be displayed in the browser if the user selects Custom Web
Time from the Display Date/Time Style (Web) menu. The user can add a semicolon (:), dash (-), or
Format a period (.) as separators. This field is clear by default. For more information about time
formats, see AR System server components and external utilities. (see page )
Session Session Specifies the number of minutes after which a session times out. The default is 90 minutes. Web
Timeout The user can set the session timeout for longer than 90 minutes, and this setting overrides the
in session timeout in the General Settings page of Mid Tier Configuration Tool.
Minutes
Animation Animated Specifies whether animated field effects (which show conditions such as state transition) are Web
Effects enabled.
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 Legacy*

toolbars.
Bar0 Coded information about Legacy*

toolbars.

toolbars.

toolbars.

toolbars.
Date and time formats

This section describes BMC Remedy AR System date and time formats.
Short date formats (see page 1370)

Long date formats (see page 1371)
Day formats (see page 1372)
Time formats (see page 1372)
Additional date or time display characters (see page 1373)

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

Format
MM/dd/yyyy Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days, four- 01/01
digit year) /2009
01/15
/2009
MM/dd/yy Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days, two- 01/01/09
digit year) 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- 01/01
digit year) /2009
15/01
/2009
dd/MM/yy Day, Month, Year (leading zero for single-digit days, leading zero for single-digit months, two- 01/01/09
digit year) 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
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)

Short Date Description Examples

Format
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- 2009/01
digit days) /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- 09/01/01
digit days) 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 Description Examples

Format
EEEE Long day format. The day is displayed in Friday, Thursday

full.
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 Description Examples

Format
h:mm:ss a Time in 12-hour format (no leading zero for single digit 1:23:45 AM, 10:23:45 PM
hours)
hh:mm:ss a Time in 12-hour format (leading zero for single digit hours) 01:23:45 AM, 10:23:45 PM

Time Description Examples

Format
H:mm:ss Time in 24-hour format (no leading zero for single digit 1:23:45, 22:23:45
hours)
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
Related topics
Setting the Web tab (see page 1368)

Setting user preferences in the BMC Remedy Mid Tier (see page 1373)
Setting user preferences settings (see page 3197)
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. (For details about the fields on each tab
in this form, see Setting the AR System User Preference form (see page ).) 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 operating system locale settings or
centralized preferences. (Operating system locale settings are used when no preference
server is designated or available.) Regardless of whether centralized preferences or
operating system locale settings are used, multiple users can use the same client
computer with individual preferences and customizations. See Setting user preferences
(see page ).
Defining business schedules using Business

Time
Business Time in BMC Remedy AR System is the ability to define periods of availability and
unavailability, workdays, and holidays to define business schedules using BMC Remedy AR
System commands.
Business Time introduction (see page 1374)

Scheduling a time segment (see page 1379)
Using time zones (see page 1385)
Business Time 2.0 commands (see page 1391)
Using the old Business Time forms (see page 1401)
Migrating Workdays and Holidays to the Business Time Segment form (see page 1409)
Business Time introduction

In this topic:
Business time architecture (see page 1375)

How Business Time 2.0 works (see page 1377)

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 Segment-Entity Association
Business Time Segment
Business Time Shared Entity-Entity Association_Join_Join — Used for query
purposes. Acts as a join form between the following forms:
Business Time Shared Entity
Business Segment-Entity Association_Join
To use the Business Time 2.0 commands (see Business Time 2.0 commands (see
page 1391)), 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 (see page ).

To define business time and implement it in your BMC Remedy AR System application, follow this
process:
1. Define any combination of time segments, business hours, and business holidays.
For workdays, define available time segments at Level 1.
For holidays, define unavailable time segments at Level 2 or higher.
Define other time segments at Level 3 or higher.
2. Add business time commands to workflow in your application.
3. Test the application.
Using the list of Time Segment IDs, Workday IDs, and Holiday IDs, the Business Time component
in AR System builds a list of available and unavailable time windows for every day in the list of IDs.
For example, consider an entity that has a Workday schedule from 8:00 A.M. to 5:00 P.M., and two
activities associated with it. The first time segment defines an available time window at a Level 3
from 10:00 A.M. to 2:00 P.M., and the second time segment defines an unavailable time window at
Level 4 from 1:00 to 4:00 P.M. The Business Time component in BMC Remedy AR System
computes the final time window list for a day as shown in the following figure.
Workday and activities for one day

The application commands described in Business Time 2.0 commands (see page 1391) work from
the final list.

Scheduling a time segment

The Business Time Segment form stores availability, level, date and time ranges, and recurrence
information about a time segment. You can add an entry to this form to schedule a business time
segment for an entity in a BMC Remedy AR System application, such as an asset or a change
request, or a group, company, or location.
Understanding levels (see page 1379)

Defining a one-time segment (see page 1379)
Defining a recurring time segment (see page 1382)
Understanding time segment entity associations (see page 1384)
Understanding time segment shared entities (see page 1385)
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 (see page 1395) 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 (see page
1374), 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.
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 (see page ).
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 (see page 1379) for more information about levels.
7. In the Category field, enter a description for the category.
This field helps determine what type of schedule time segment the item is (for example,
blackout, maintenance, and so on.) Although it is not a required field, it can help you
categorize your time segments.
8.
8. From the Timezone list, select a time zone.

See Using time zones (see page ) 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 (see page 1382) for
more information.
Find Next Free — Finds the next free time slot based on the Start Date and Start
Time and 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 (see
page ).
11.
11. Enter the Start Date, Start Time, End Date, and End Time for the duration of the time
segment.
If your day ends at midnight, select the End of Day check box. Then, any value in the End
Time field is ignored, and the day ends at midnight.
12. In the Earliest Start Time field, enter the earliest preferred start time for which to schedule
the time segment.
The search for a start time starts with the Start Date and Start Time and find the first
available time with the specified duration. If no time slot is found within the same day, it
continues to the next day, starting after the Earliest Start Time. If this field is blank, the
search for the next available time continues from 12:00 A.M. of the next day if necessary.
13. 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 (see page ).

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 (see page ).
Assignee Groups — Groups specified on Business Time Segment form. For more
information, see Scheduling a time segment (see page ).

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.
Using time zones

The Business Time Segment form includes a Timezone list from which you can select time-zone
values. When the AR System server executes a Business Time command and encounters a time
segment with a time zone, it adjusts the time to match the time in the specific time zone.
Using the time zone value of the Level 1 time segment (see page 1387)

Using offset hours in Business Time 2.0 (see page 1390)
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 (see
page 1386)
Daylight savings time zone difference between AR System server and the Schedule scenario
(see page 1386)
Undefined time zone scenario (see page 1387)
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
Case 7: If you add 8 hours, the result is 1/24/2008 3:30:00 AM (10 AM-11 AM and 12 PM-1
The following figure illustrates this example.
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 (see
page )) 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 (see page ) 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.

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 (see page 1393) 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 (see page 1391)

Business Time application commands (see page 1393)
Application-Bus-Time2-Get-Free-Window scenarios (see page 1395)
Using application commands with daylight saving time (see page 1397)
Business Segment-Entity Association commands (see page 1398)
Application-Get-Next-Recurrence-Time (see page 1399)
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:
Application-Bus-Time2-Add (see page 1393)

Application-Bus-Time2-Diff (see page 1394)
Application-Bus-Time2-Subtract (see page 1394)
Application-Bus-Time2-Get-Next-Window (see page 1394)
Application-Bus-Time2-Get-Free-Window (see page 1395)
Important
The Olson (also Olsen) time zone format is the default on AIX when time zones are set
through System Management Information Tool (SMIT). When the Olson time zone format
is used with an AR System server running on AIX, however, the AR System server
miscalculates dates and times when executing Business Time application commands.
Therefore, BMC recommends that you use the POSIX time zone setting for AR System
servers running on AIX. When the POSIX format is used, the AR System server correctly
calculates dates and times affected by Business Time application commands.
Application-Bus-Time2-Add
The Application-Bus-Time2-Add command adds the requested offset to the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time into
the future.
Use the following syntax for the Application-Bus-Time2-Add calculation:

Application-Bus-Time2-Add *"*startTime" ["<amount>" ["<amountUnits>"
["<businessTimeSegmentName1>" " <businessTimeSegmentName2>" . . . ]]]
The <startTime parameter> is required in this command. This parameter must be a value
such as a field reference ($<fieldName>$). Other fields are optional and use the default value if
not provided. You can specify multiple business activity names.
For example, to add one day, use the following calculation:

$PROCESS$ Application-Bus-Time2-Add "$<fieldName>$" "<amount>"

"<amountUnits>"
This adds one day to the value in <fieldName>. In the example, <fieldName> is <startTime>
. <amount> (offset) is set to 1, and <amountUnits> is set to 4 (representing days), thus adding 1
day to the calculation. The final syntax looks like:
$PROCESS$ Application-Bus-Time2-Add "$8/26/2004$" "1" "4"
Application-Bus-Time2-Diff
The Application-Bus-Time2-Diff computes the difference between the start time and the
end time. The command returns an integer representing the difference in seconds. Use this
command to compare two different times (start time and end time) to get the actual business time.
Use the following syntax for the Application-Bus-Time2-Diff calculation:

Application-Bus-Time2-Diff "<startTime>" "<endTime>"
["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]]
The <startTime> and <endTime> parameters are required in this command. Other fields are
optional and use the default value if not provided. You can specify multiple business activity
names.
Application-Bus-Time2-Subtract
The Application-Bus-Time2-Subtract subtracts the requested offset from the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time in the
past.
Use the following syntax for the Application-Bus-Time2-Subtract calculation:

Application-Bus-Time2-Subtract "<startTime>" ["<amount>"
["<amountUnits>" ["<businessTimeSegmentName1>"
"<businessTimeSegmentName2>" . . . ]]]
The <startTime> parameter is required in this command. Other fields are optional and use the
default value if not provided. You can specify multiple business activity names.
Application-Bus-Time2-Get-Next-Window
The Application-Bus-Time2-Get-Next-Window command returns the start of the next
available or unavailable time segment that is <duration> seconds long. If <duration> is 0 (the
default), the command returns the start of available time segment or the start of unavailable the
time segment.
Additionally, depending on the <windowFlag>, the command returns one time segment or all the
time segments between <startTimeRange> and <endTimeRange>.

Use the following syntax for the Application-Bus-Time2-Get-Next-Window calculation:

Application-Bus-Time2-Get-Next-Window "<startTimeRange>"
"<endTimeRange>" ["<duration>"] ["<windowFlag>"]
["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]
Application-Bus-Time2-Get-Free-Window
The Application-Bus-Time2-Get-Free-Window command returns the start of the next
available or unavailable free time segment at the same level or a higher level that is <duration>
seconds long. A free time segment at Level <level> and Duration <duration> is one where no
other time segment at the same or higher level as <level> overlaps, or starts or ends in the
<duration> of this time segment. After a free time segment is obtained, it can be created as
available or unavailable. The default value for <duration> is 0, which returns the next available
time segment.
Use the following syntax for the Application-Bus-Time2-Get-Free-Window calculation:

Application-Bus-Time2-Get-Free-Window "<startTimeRange>"
"<endTimeRange>" ["<level>"] ["<duration>"] ["<earliestStartTime>"]
["<latestEndTime>"] ["<businessTimeSegmentName1>"
"<businessTimeSegmentName2>" . . . ]
The command considers all Business Time Segments at a certain level or above and treats them
as unavailable, regardless of whether they are available or unavailable. If Level 1 and 2 time
segments are present, they are always considered and are taken as available and unavailable,
respectively.
Application-Bus-Time2-Get-Free-Window scenarios
In this topic:
No Earliest Start Time or Latest End Time scenario (see page 1395)
Earliest Start Time for Level 2 scenario (see page 1397)
Earliest Start Time is specified or unspecified scenario (see page 1397)
Duration of two hours scenario (see page 1397)
Duration of 7200 seconds scenario (see page 1397)
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

00:00 PM" 2 3600 "11:00:00 AM" "" "" "Work1" "Act1" "Act2" "Act3"
In this scenario, if the Earliest Start Time for Level 2 is 11:00 A.M., the return value at Level 2 is
1121295600 (July 13, 2005, 4:00 P.M.).
Earliest Start Time is specified or unspecified scenario

00:00 PM" 2 3600 "5:00:00 AM" "2:00:00 PM" "" "Work1" "Act1" "Act2"
"Act3"
If the Earliest Start Time is 5:00 A.M. (or if it is not specified) and if the Latest End Time is 2:00 P.
M., the return value at Level 2 is 1121270400 (July 13, 2005, 9:00 A.M.).
Duration of two hours scenario

If the duration required is two hours, "" is returned for Level 2.
Duration of 7200 seconds scenario

If the Level is 4 and the duration is 7200 seconds, 1121266800 (July 13, 2005, 8:00 A.M.) is
returned.
Using application commands with daylight saving time

In this topic:
Adding 1 hour to the start time scenario (see page 1398)

Difference of 1 hour between start time and end time scenario (see page 1398)
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:
Application-Bus-Time2-Assoc-Add (see page 1399)

Application-Bus-Time2-Assoc-Diff (see page 1399)
Application-Bus-Time2-Assoc-Subtract (see page 1399)
Application-Bus-Time2-Assoc-Get-Next-Window (see page 1399)
Application-Bus-Time2-Assoc-Get-Free-Window (see page 1399)
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>"
"<businessTimeSegmentName2>" . . . [-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>"
["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e
"EntityID1" "EntityID2"... ]]
Application-Bus-Time2-Assoc-Subtract
Use the following syntax for the Application-Bus-Time2-Assoc-Subtract calculation:
Application-Bus-Time2-Assoc-Subtract "<startTime>" ["<amount>"
"<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2"... ]]]]
Application-Bus-Time2-Assoc-Get-Next-Window
Use the following syntax for the Application-Bus-Time2-Assoc-Get-Next-Window
calculation:
Application-Bus-Time2-Assoc-Get-Next-Window "<startTimeRange>"
"<endTimeRange>" "<duration>" "<windowFlag>"
["<businessTimeSegmentName1>" " <businessTimeSegmentName2>" . . . [-e
"EntityID1" "EntityID2" . . . ]]
For more information, see the BMC Knowledge Base article KA311064.
Application-Bus-Time2-Assoc-Get-Free-Window
Use the following syntax for the Application-Bus-Time2-Assoc-Get-Free-Window
calculation:
Application-Bus-Time2-Assoc--Get-Free-Window "<startTimeRange>"
"<endTimeRange>" "<level>" "<duration>" "<earliestStartTime>"
"<latestEndTime>" ["<businessTimeSegmentName1>"
"<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2" . . . ]]
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 (see page ).

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.
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 (see page 1401)

Scheduling holidays (see page 1404)
Tips for entering dates and times for holidays (see page 1405)
Adjusting the time across midnight for holidays (see page 1406)
Defining business hours using offset hours (see page 1407)
Old Business Time commands (see page 1408)
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.
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. (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 (see page ).
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.
Application-Bus-Time-Add (see page 1408)

Application-Bus-Time-Diff (see page 1409)
Application-Bus-Time-Subtract (see page 1409)
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 (see
page ).
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>"
<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>"
<workdayScheduleName>"]]]]
The <startTime> parameter is required in this command. Other fields are optional and use the
default value if not provided. You can specify multiple business activity names.
Migrating Workdays and Holidays to the Business Time

Segment form
This topic provides tips you can use when migrating your Business Time Workdays and Holidays
to the Business Time Segment form.
In this topic:
Migrating Workdays considerations (see page 1410)

Migrating Holidays considerations (see page 1410)

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.
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 (see page 2839).
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.
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 (see page ).
You cannot delete the Alert Events form and its original fields, but you can add fields and workflow
to the form.
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 (see page )
.
If a web user has access to multiple forms that have alert list fields, BMC Remedy AR System uses
the first form that it finds that contains an Alert List. Therefore, if the user has permission to
multiple forms containing an alert list, you cannot always predict which form will be used. BMC
recommends making sure that each group can access only one alert list form. This option enables
you to create forms with different workflow and different fields for different groups.
Deleting unread alerts

The CleanupAlertEvents escalation is automatically created with the Alert Events form. If enabled,
this escalation deletes all unread alerts older than 30 days.
Initially, the CleanupAlertEvents escalation is disabled. You can enable it and customize it
according to your needs.

Registering users for alerts

The AR System Alert User Registration form is installed with BMC Remedy AR System. Entries in
this form identify each alert user and the method or methods by which they receive alerts. Users
can have multiple entries in this form, as long as each entry represents a different alert destination.
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 (see page ).
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 (see page 1417).)
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
Time created or modified. 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
Time (secs) limit. An escalation runs every 10 minutes to delete expired entries. If an entry has expired but the escalation has
not yet run, the user continues to receive alerts.
Short Used for optional supporting information. If you do not need to use this field, leave the default value N/A in the
Description field.
Plugin Defines the way alerts are sent for this user registration. The drop-down field menu takes its entries from the AR
Name System Alert Delivery Registration form. Two methods are installed with BMC Remedy AR System:
Alert API — Send alerts to a browser via the AR System Alert API.
Web Service — Send alerts via web service, such as the AR System Alert Web services plug-in, ARSYS.
ALRT.WEBSERVICE.
To use the Web Service plug-in, you must create a web service using the installed AR System Alert Web service
WSDL. See Using Web services with alerts (see page ).
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
Plugin this field.
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 Remedy AR System server.
For Web services, you use the Reregister method to reset the Registration Time. See Using Web services with
alerts (see page ).
Update An optional status field that controls whether or not to update the Sent Successfully field on the Alert Events form
Sent Flag when an alert is successfully delivered. Updating the Sent Successfully field for all Alert Events entries can have
a performance impact on a busy server, so this field allows you to manage performance by controlling whether the
Sent Successfully field is used.
Using the alert list in a browser

Browser users can view the alert list by opening a form that contains an alert list field, such as the
Alert List form or any form that you create, as long as it contains an alert list field.
In this topic:
To create and publish a web-based alert list (see page 1415)

To enable a preference server for the Web (see page 1415)
To configure user preference values for alerts on the Web (see page 1415)
To create and publish a web-based alert list
1. Create a regular form (see page 2404)on one server in your BMC Remedy AR System
installation where the mid tier is also installed.
2. Add an alert list field (see page 2481)to the form.
3. Make this form accessible in a browser through a URL (see page 2963).
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 (see page ).
2. Under General Settings (see page 431)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 (see page
).
a.
a. In the Alert Servers field, enter the name of each server (separated by commas)
from which users receive alerts.
Alerts from these servers are visible in the Web-based alert list. Users do not need to
be logged in to these servers to receive alerts or to display the originating request.
b. In the Refresh Interval field, enter the number of minutes between each automatic
refresh of the alert list.
A setting of 0 indicates no refresh interval.
Each server specified under Alert Servers is queried for new alerts, and these alerts
are displayed in the Web-based alert list.
Using Web services with alerts

BMC Remedy AR System can send alerts to the plug-in server for users registered with the Web
Services Plugin Name in the AR System Alert User Registration form. You can configure alerts to
go to the AR System Alert Web Services plug-in installed with BMC Remedy AR System, or to
another plug-in that you create.
Note
To send alerts via Web service, the AR System Web services plug-in ARSYS.ARF.
WEBSERVICE must be installed. See Setting up the environment for web services (see
page 3440).
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 (see page 3430).
To register a user to receive alerts through the AR System Alert Web Services
plug-in
1. Create a Web service (see page 3444)that uses the alertNotification.wsdl.

2. Create an entry for the user in the AR System Alert User Registration form.
a.
Home
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>
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 predefined assignment methods are used to identify an
assignee for the request. See Integrating the BMC Remedy Assignment Engine into an application
(see page 885).
Auto-assignment methods (see page 1419)

Assignment process flow (see page 1420)
Assignment Engine Administration Console introduction (see page 1421)
Assignment Engine forms (see page 1421)
For information about configuring assignments using BMC Remedy ITSM, see Configuring
assignments.
Auto-assignment methods
The assignment method determines who is assigned to an issue when more than one person
matches the qualification. In such cases, the following assignment methods can be specified in an
assignment rule to automatically assign the issue:

Round Robin — Assigns the issue to the person who has gone the longest since receiving
an assignment.
For example, if person A was last assigned an issue at 9:00 A.M., and person B was
assigned an issue at 10:30 A.M., person A is selected.
Load Balance by Number — Assigns the issue to the person who has the fewest number
of issue assignments.
For example, if person A is assigned 2 issues and person B is assigned 3 issues, person A
is selected.
Load Balance by Capacity — Assigns the issue to the person who has the largest unused
capacity.
For example, if person A has a capacity rating of 10 and is assigned 5 issues, then the
unused capacity is 5. Similarly, if person B has a capacity rating of 20 and is assigned 8
issues, then the unused capacity is 12. In this case, person B is selected because of the
higher unused capacity.
But if person A and person B have a capacity rating of 10 and are assigned 10 issues, in
this case, the next open issue is assigned to the person who has gone the longest since
receiving an assignment.
Note
For the Load Balance by Number and Load Balance by Capacity assignment
methods, it is possible that two or more people qualify for an issue. In such cases, the
assignment does not happen in alphabetical or random order, but in the sequence in
which the records are fetched. This sequence is determined by the sort order on the
assignee form, if specified; else, in the order in which the records are created.
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.
6. If all the rules fail to return a set of assignees, the assignment process fails.
Assignment Engine Administration Console introduction

To set up auto-assignment processes, forms, and rules, you use the Assignment Engine
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.
For information on Assignment Engine server settings, see Configuring the Assignment Engine
server settings (see page 653).
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 Description

Studio
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

Form name in BMC Remedy Developer Description

Studio
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 (see page ).

Enabling and disabling full text search

Full text search (FTS) is installed by default with the BMC Remedy AR System server. This section
discusses the capabilities, performance, and administration of the FTS feature.
Setting up FTS to search across multiple forms (see page 1424)

Re-indexing considerations (see page 1432)
Defining a field for FTS (see page 1434)
How FTS indexing works (see page 1437)
Performing searches with FTS (see page 1442)
FTS index migration (see page 1453)
Enabling FTS high availability (see page 1454)
FTS Operation types (see page 1456)
FTS is typically much faster than using the native database searching functionality when searching
in long text fields. It is also the only method available in BMC Remedy AR System for searching
text within attached documents.
With FTS, you can use your knowledge base. You can access your company's history of solving
problems, which is sometimes stored in long text fields or attachments. With the FTS option, you
can easily search long text fields to find solutions to related problems.
FTS solves many problems that users encounter when performing database searches, including:
Searching long text and attachment fields. The FTS option enables you to index character,
diary, and attachment fields for searching, and then matches entries from those fields
against the search criteria that you specify. Like database indexes, an FTS index can
greatly decrease the time required for a database search.
Improving search performance by searching large volumes of data.
Defining how the server interprets wildcards to customize search performance to your
specific needs.
Ranking search results according to their relevance to the search criteria. The more relevant
a search result is, the greater the weight. For more information, see Causing accrued and
weighted results with FTS (see page ).
To enable FTS
1. Install FTS with BMC Remedy AR System. (See Installing in BMC Remedy ITSM
Deployment online documentation.)
2. Configure the server for FTS. (See Configuring full text search (see page 546).)
3. Index fields for FTS. (See Defining a field for FTS (see page ).)
4.
4. (Optional) Add a form search field to a form. (See Providing a shortcut for specifying
expanded FTS qualifications (see page ).)
5. (Optional) Set up forms for multiple-form FTS. (See Setting up FTS to search across
multiple forms (see page ).)
6. Re-index, as needed. (See Re-indexing considerations (see page ).)
To disable FTS
2. On the FTS tab,
To disable full text searching, select the Disable Full Text Searching check box.
To disable FTS indexer, select the Disable FTS Indexer check box.
For more information, see FTS tab configuration options (see page 546).
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 multi-form FTS (see Configuring forms
for multiple-form FTS (see page )).
2. Configure the server for multi-form FTS (see Configuring the relevancy weight for fields in a
multiple-form FTS (see page )).
3. Update the AR System Multi-Form Search form (see Performing searches on multiple forms
(see page )).
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 (see page )).
5. (Optional) Use date and time fields on your search form (see Using date and time fields on
your search form (see page 1431)).
Behavior of multi-form FTS
If a user does not have permission to the Request ID field (field ID 1), the entire row is
eliminated from the multi-form FTS results.
The fields permissions of multi-form search enabled fields are not considered during multi-
form search. This causes the content for all the multi-form search enabled fields to appear in
the search results.
Configuring forms for multi-form FTS

This topic explains how to set form properties to include a form in a multi-form search.

To configure a form for a multi-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
multi-form searching by default.
See Defining a field for FTS (see page ).
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 (see page ).
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 (see page ).
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 (see page ) for more information.
You can set a title field, environment, and keyword on each form. See Configuring forms for
multiple-form FTS (see page ).
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 triggered .
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 (see page 1428)). 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 (see page
).
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.
2. If you have an event that constructs your filter query, create a Set Fields active link that
copies the value of the date and time field to the hidden integer field.
This causes the client to convert the date and time string to the appropriate integer value,
which takes into account the locale and time zone of the client and normalizes it to the date
and time used by the server, for example:
Hidden_Integer [1250143200]
3. Use the value of the hidden integer for the value of the date that you are passing.
The resulting filter query would look something like this:
'modifiedTime' >= "1250143200"
Re-indexing considerations
Most of the time, you should not have to rebuild your FTS indexes because the AR System server
periodically optimizes them after BMC Remedy AR System requests are added, changed, or
deleted. Some exceptions are:
If you change your Ignore Words List, Root Word List or Thesaurus you must rebuild the
FTS indexes (re-index). See How FTS indexing works (see page ).
Note
If you change your Ignore Words List, Root Word List or Thesaurus and you do
not re-index then only the entries inserted, deleted, or modified after that time are
affected.
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 (see page ).
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.
Time required to rebuild a set of indexes (see page 1433)

Re-indexing due to field and form property changes (see page 1433)
After modifying the Ignore Words List, Root Word List, or Thesaurus (see page 1433)

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
For more information about locating your FTS indexes, see Estimating the size of the FTS index
(see page ).
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 (see page ).
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 (see page ).
If you change the Literal FTS Index field property for a field, the field is re-indexed.
If you change the Strips Tags For FTS 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 (see page 558) or FTS tab configuration options (see page ).
Note
If you modify Ignore Words List, Root Word List, or Thesaurus, you must restart the
server for the changes to take effect.
Defining a field for FTS

Indexing table fields (see page 1436)

Boosting document relevance (see page 1437)
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 (see page ).

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

customer.
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.
How FTS indexing works

BMC Remedy AR System uses the AR System Server Java process 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 (see
page 274).
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.
The Full Text Search (FTS) has smart processing for all the entries to be indexed. The smart
process optimizes the processing of the redundant entries and results better indexing performance.
It provides the following functionality:
Avoids processing of duplicate indexing requests from JMS and ft_pending.

Does not depend on the JMS messaging based communication for the FTS indexing. It
uses only JMS as a wakeup signal and also adds a scheduler for any periodic missed
entries.
Avoids logically redundant request by cleaning the requests from ft_pending during the
insertion or processing. System ensure that only the redundant entries are deleted from the
system so that work required for these entries is completed by some other entry.
Optimizes the synchronization of global or form and entry level re-indexing in such a way
that the resources in the server (CPU and threads) are optimally used for indexing.
Note
BMC recommends that you perform global re-index or schema re-index during off-
peak hours, such as during a maintenance window.
Re-indexing of entire schema or form deletes the existing indexes and creates the
indexes again. So the re-indexing of a form may be faster as compared to
individually updating the index for more number of entries.
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 (see page 1439)

How FTS indexing works for localization and attachment file formats (see page 1440)
Causing accrued and weighted results with FTS (see page 1440)
Tokenization rules used in FTS (see page 1441)
Estimating the size of the FTS index (see page 1441)

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 (see page 4396).
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 (see page ).
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.
2. Multiply by a minimum of 2.
The ratio of the size of the FTS index to source text can differ widely based on, for example,
the size of your Ignore Words List.
Performing searches with FTS

FTS is transparent to users. If the server has a Full Text Search license and the full text feature is
configured correctly, full text searching is activated.
If full text searching is activated and the field is indexed for FTS, FTS is used.
If full text searching is not activated or the field is not indexed for FTS, AR System uses the
search capability of the underlying database. Under these conditions, attachment fields
have only their names searched.
Field permission-related behavior for FTS fields is the same for non-FTS fields.
Users enter search criteria in the same way, whether they are using FTS or not, with the exception
of accrual searches.
Searching in a field indexed for FTS (see page 1442)

Searching for words or phrases (see page 1443)
Performing an accrue search (see page 1445)
Performing a literal search (see page 1446)
Searching for variations of word stems (see page 1448)
Searching with a wildcard character (see page 1448)
Using the query-by-example method (see page 1449)
Restricting search criteria with a parametric FTS (see page 1452)
Limitations of FTS (see page 1452)
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 (see page ) 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 (see page 1448).
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 (see page 557).
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

QBE Match Effect on search criteria

property
setting
%left,center,right%
The client adds wildcards to the start and end of the search. The server makes a special interpretation of these
search criteria for a full text search and places a leading and trailing wildcard around each search term. For
example:
%left%,%center%,%right%
Leading left,center,right%
The client adds a wildcard to the end of the search. The server makes a special interpretation of these search
criteria for a full text search and places a trailing wildcard after each search term. For example:
left%,center%,right%
Equal left,center,right
The client does not add any wildcards to the search string, but it uses the EQUAL (=) operator instead of the LIKE
operator. This has no effect on the server's full text search.
Setting QBE Match for a field

1. On BMC Remedy Developer Studio, open the form and select the required field.
2.
2. On Properties section of the field, on the Database property, select the QME match from
the QME Match drop-down list.
To set the default preference for the QME match

1. On BMC Remedy Developer Studio, on the Windows menu, select Preferences.

2. On the Preferences window, on BMC Remedy Developer Studio, select Form.
3. On the Form preferences, select the required Default QBE Match setting to change the
preference.

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 (see page ).
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 (see page 546).

Full text searches that involve a field reference to the right of the relational operator are not
supported. A warning message occurs that indicates that the query was treated as a
database query instead of an FTS query. The presence of 'Target' in the following
example returns the warning message if the Short Description field is indexed for FTS:
'Short Description' LIKE 'Target' + "ing"
If no variables are to the right of the LIKE keyword in the statement, FTS handles the
search. For example:
'Short Description' LIKE "block" + "ing"
In this example, the search is handled by FTS because the known values (block and ing)
are combined to form one known value (blocking).
FTS index migration

AR System uses the Lucene 4.9 search engine for Full Text Search (FTS) and uses a schema-
specific multi-file index format to optimize read/write operations, resulting in searches that are
about three times faster and indexes that are about 40 percent smaller than the Lucene 2.9 index
used in earlier releases.
FTS migration utility

The Full Text Search (FTS) index migration utility arftsutil migrates the 2.9 index to the 4.9 multi-
file format. The arftsutil utility does two things:
1. Updates Apache Lucene 2.9 indexes to 4.9

2. Splits the index into multiple schema-specific files
The two versions of arftsutil are:
arftsutil.bat - For Windows servers

arftsutil.sh - For UNIX servers
The arftsutil utility is embedded in the AR System interactive GUI installer and runs automatically
if a single-file Lucene 2.9 index is detected. If the GUI installer detects that a Lucene 4.9 index is
present, it does not execute arftsutil again.
The AR System GUI installer has no option to override automatic migration but you can bypass the
migration by running the installer in silent mode with the following option:
-J BMC_AR_SKIP_FTS_INDEX_MIGRATION=true

To manually migrate a 2.9-based index, run arftsutil from the command line.
Windows servers:
<C:\BMCRemedy\AR>arftsutil.bat -d "<COLLECTION DIR PATH>" -c "<FTS

CONFIGURATION DIR PATH>"
UNIX or Linux servers:
</BMCRemedy/AR/arftsutil.sh -d "<COLLECTION DIR PATH>" -c "<FTS CONFIGURATION

DIR PATH>"
Note
Schema-specific index files are stored in the Full-Text-Collection-Directory

configuration parameter in the ar.cfg file, with a unique schemaId subdirectory for each
schema index. For example, if the ar.cfg file specifies the collection directory as C:
\Program Files\BMC Software\ARSystem\ftsconfiguration\collection and the search
user creates a schema named TestForm that has a schema ID of 1234, the index
documents for this schema are created under C:\Program Files\BMC
Software\ARSystem\ftsconfiguration\collection\1234.
Related topics:
Performing a new installation in BMC Remedy ITSM Deployment documentation.

Running the installer in silent mode in BMC Remedy ITSM Deployment documentation.
Enabling FTS high availability

In a server group environment, Full Text Search can be configured for high availability (HA) so that
search requests are completed even when a server in the group becomes unavailable. By
designating multiple servers as indexer servers, if one server goes down another server
can process the queued search requests.
In FTS High Availability configuration,
Every server with valid BMC Remedy AR System Server Group Operation Ranking acts as
an indexer server.
Each indexer has its own copy of indexes.
The searcher server sends the search requests to indexer servers.
In event of an indexer server failure or service interruption, a search request is routed to the
highest ranking available indexer server to complete the search request.

Full Text Search High Availability example
You can install more than one FTS server in a server group. Each FTS server is defined in AR
System Server Group Operation Ranking form acts as an indexing server and provides FTS
search services to other servers in the server group. If the FTS Rank 1 server becomes
unavailable, the FTS server that is ranked 2 contains the redundant FTS data and is used for the
failover. So all the servers in the server group operate as an independent FTS server, providing
high availability and service failover.
For more information about how FTS high availability works in a server group environment, see
High-availability architecture for FTS (see page 549) and Configuring full text search for a server
group (see page 349).
For more information about the BMC Remedy AR System Server Group Operation Ranking, see
Setting failover rankings for servers and operations (see page 345).
Note
To configure FTS high availability and failover, all FTS plug-ins must run on same port.
Video: Full Text Search High Availability for server groups
This brief video (4:10) explains FTS High Availability.
Full Text Search High Availability for Server Groups

Related topics
High-availability architecture for FTS (see page 549)

Configuring FTS High Availability failover after an upgrade

When upgrading to BMC Remedy AR System 9.0, it may be necessary to reconfigure the AR
System Server Group Operation Ranking form to enable failover, ensuring that search requests
are fulfilled if one of the indexer in your server group becomes unavailable. If you upgrade to BMC
Remedy AR System 9.0 from earlier versions, consider the following:
Upgrading from 7.6.04, 8.0, 8.1, or 8.8: You should reconfigure failover in the FTS ranking
form, after the upgrade is complete. In this case, an extra plugin entry ARSYS.ARF.FTS
ARSYS.ARF.FTS is created on the indexer machine. There is no impact of this entry and
you can ignore it.
Upgrading from 7.6.04 SP5, 8.1 SP1 or SP2: You need not reconfigure failover in the FTS
ranking form.
To enable failover with the AR System Server Group Operation Ranking form , refer to Setting
failover rankings for servers and operations (see page 345).
For information on enabling FTS high availability, refer to Enabling FTS high availability (see page
).
Related topic
FTS Operation types

The mapping between BMC Remedy AR System server prior to 9.0 version and BMC Remedy AR
System server 9.0 version for operation types for FTS is as follows:
BMC Remedy AR System server implementation BMC Remedy AR System server implementation
(For versions lower than 9.0) (For 9.0 version )
Op Code Description Op Code Description
1 Index Entry 0 Create Entry
1 Set Entry

BMC Remedy AR System server implementation BMC Remedy AR System server implementation
(For versions lower than 9.0) (For 9.0 version )
3 Index Entry
2 Un-index Entry 2 Delete Entry Index
3 Index Row 0 Create Entry
1 Set Entry
3 Index Entry
4 Un-index Row 2 Delete Entry Index
5 Index Field 7 Re-Index Field
6 Index Field – Re-Index Change 7 Re-Index Field
(For example: Table field definition

Change)
7 Index Field - Literal Change 7 Re-Index Field
8 Un-index Field 8 Delete Field Index
9 Doc Boost 5 Re-Index Form
(Doc boost field - 177 added/deleted)
10 Re-Index form 5 Re-Index Form
11 Re-Index Form Since 6 Re-Index Form Since
12 Un-index Form 4 Delete Form Index
13 Re-Index Field for adding title 7 Re-Index Field
14 Re-Index Field for removing title 7 Re-Index Field
15 Un-index Title Field 7 Re-Index Field
Controlling BMC Remedy AR System through

email
This section explains how to transform email into an interface that communicates with the BMC
Remedy AR System server using the BMC Remedy Email Engine service.
BMC Remedy Email Engine terminology (see page 1458)

How BMC Remedy Email Engine works (see page 1458)
Setting up outgoing email (see page 1464)
Setting up incoming email (see page 1520)
Setting up UNIX mailboxes (see page 1557)
Creating and using email templates (see page 1559)

Email Engine forms (see page 1605)
BMC Remedy Email Engine terminology

Term Meaning in the context of BMC Remedy Email Engine
Mail A computer system within your environment that is running a third-party software program that processes incoming
server 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
mail server stops working. You can define this by using the BMC Remedy AR System Email Failover Mail Server form.
server For more information, see Multiple mail server support (see page ).
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
mailbox messages from a specific email account on a mail server. Email messages in this email account are assumed to be
directed to the BMC Remedy Email Engine. The installation program provides an option for creating and configuring
an initial incoming mailbox. You can use this mailbox to get started with BMC Remedy Email Engine; you can then
change these settings or configure additional mailboxes.
Outgoing A mailbox containing the information required by BMC Remedy Email Engine to create and send messages. BMC
mailbox Remedy Email Engine uses this mailbox to send notifications, send the results of queries, and so on. The
installation program provides an option for creating and configuring an initial outgoing mailbox. You can use this
mailbox to get started with the BMC Remedy Email Engine; you can then change these settings or configure
additional mailboxes.
Instruction A term used in the following ways:
In a broader sense, instructions see all the parameters contained in an email message that perform certain
actions; for example, logging in to the server, querying for all tickets assigned to a user, and returning the
results in HTML format.
In a narrower sense, instructions see a specific set of actions used in an email message; for example, Query,
Submit, or Modify. The term Instruction can also be used as an alias for Action in a label/value pair.
How BMC Remedy Email Engine works

Improving the appearance of your email (see page 1460)

Multiple mail server support (see page 1462)

This topic presents a sample scenario that demonstrates how Email Engine interacts with the BMC
Remedy AR System and your mail server. The following figure presents a sample environment for
an Email Engine implementation, including the flow of activity.
How Email Engine interacts with the AR System server

In the XYZ Company, Shelly needs a list of the latest issues stored in the Help Desk (HD) Incident
form. She wants the results of this query to be returned in an easy-to-read email. Also, Shelly
wants to make sure that her coworkers, Katie and Mark, will be copied with the results of this
query. All of the steps that Email Engine and the users must take to make this happen follow.

1. The local administrator installs Email Engine, configuring Incoming and Outgoing mailboxes
to work with the company mail server.
After Email Engine is started, it contacts the AR System server. It then reads all the entries
in the AR System Email Mailbox Configuration form and creates Incoming and Outgoing
mailboxes based on that information.
2. After the administrator notifies the user base that Email Engine is running, Shelly composes
an email instructing the Email Engine to perform a query of the HD Incident form. She uses
specifically formatted instructions to be read and understood by the Email Engine. She
sends this message to an email account on the company mail server that Email Engine polls
for incoming.
3. 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 (see page 1460).
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. 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 (see page ).
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.
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 (see page 1464)

Types of outgoing email (see page 1466)
Sending notifications (see page 1467)
Sending outgoing email with the Email Messages form (see page 1485)
Sending professional looking reply emails (see page 1503)
Encoding user-defined text in outgoing HTML email (see page 1519)
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 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.
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 (see page 604)

Defining a workflow to send email notifications (see page )
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 (see page ).
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 (see page 1467)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 perform is 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 (see page 1503).

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 (see page 1485)for
configuring or troubleshooting the Email Engine. The average user never sees or needs this
form.
Sending notifications
Defining a workflow to send email notifications (see page 1469)

Dynamically assigning templates to outgoing email (see page 1478)
Displaying date-time or numeric values in email notifications (see page 1481)
Deleting email notifications (see page 1481)
Using templates with outgoing email (see page 1482)
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.
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 (see page 604).
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 (see page 2962).
6. In the User Name field, enter the name of the users or groups to notify. For each recipient,
an entry is made in the AR System Email Messages form (see the following figure). You can
enter a maximum of 255 characters.
To specify one or more recipients, enter any of the following choices separated by hard
returns (the server evaluates each line separately) in the User Namefield:
AR System user logins
AR System groups
Email addresses
Include the email domain name if you are entering an email address (for example,
Joe.User@acme.com) or a keyword (for example, $USER$@acme.com). The order
in which these entries appear is the order in which the Email Engine searches for
addresses. If the contents of the User Name field do not match an existing User or
Group definition, the system interprets the field contents as a literal address and
sends the notification to that address by SMTP, IMAP, MAPI, or POP mail protocols.
This address can be an email address representing users who are not using BMC
Remedy AR System, an alias for a group, or an email address representing a
program.
Warning
Do not use group notifications as an email system for broadcast type items
because the server processes a notification for each member. An email
alias is more efficient. If you are using a field reference (for example,
$Submitter$), do not include the domain name as part of the notification
because the email address is being read from the Email Address field of the
user's entry in the User form.

7. Enter a value in the Priority field; ranges of 1 to 10 are acceptable. By default, emails are
sent out from the Email Engine in the order they were received, not in the order of priority.
8. To set properties in the EmailDaemon.propertiesfile so that the Email Engine sends high-
priority emails first and then lower priority emails, change the following property as shown:
*SortMessages= true *
For more information, see Email daemon issues when AR System server stops (see page
4672).
9. From the Mechanism field, select Email.
The Fields, Messages, and Templates tabs are activated. For more information, see
Defining fields in email notifications (see page 1471) and The Messages and Templates tabs
(see page 1474).
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
(see page ).)
To be able to send the field contents, make sure that users being notified have the
necessary permissions. See Access control (see page 1273).
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 (see
page ).)
The Messages and Templates tabs

The Messages and Templates tabs allow you to determine at run time which user the email came
from, which mailbox to use, which templates to use, and so on. The fields in these tabs are
optional. If you leave these fields blank, the settings relating to the mailbox entered in the Mailbox
Name field apply. Or, if the Mailbox Name field is empty, the default outgoing mailbox settings
apply. The default outgoing mailbox is the first mailbox created, or you can specify another mailbox
in the AR System Email Mailbox Configuration form.
Any entries in the fields in the Messages and Templates tabs will override the default settings. If
there are no entries in the Messages and Templates tabs, and no default mailbox exists, an error
message will be generated.
Defining messages in email notifications

Use the Messages tab to override your mailbox configuration settings for the Notify action. If you
leave these fields blank, the values in your notification email default to your current mailbox
configuration settings.
To define the Messages tab
1. In the Mailbox Name field, enter the name of the outgoing mailbox that you want to handle
the notifications if you do not want to use the default mailbox.
You can use a field or a keyword to substitute the mailbox name. This mailbox name should
correspond to a valid mailbox configured in the AR System Email Mailbox Configuration
form.
2. Enter information in the From, Reply To, CC, and BCCfields:
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 (see page ).
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 (see page )

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. 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.
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.
c. Enter 'TR.Impact' != $NULL$ as the Run If qualification.

Here you want the filter to execute on Submit or Modify whenever the value of the
Impact field changes (that is, when the filter detects there is a new transaction value
in the Impact field).
10. In the If Action tab, create a Set Fields action with the following parameters:
a. Read the value for the field from the XYZ_Templates form.
b. Enter 'Impact' = $Impact$ as the Set Fields Run If qualification.
c. Select Header Template as the field name and $Template Name$ as its value.
With this workflow, the name of the proper template, based on its impact, is stored
with each incident. Here you define the filter to query the XYZ Templates form
created earlier where 'Impact' = $Impact$, and you set the value of the Header
Template field on the XYZ Incident form from the value of the template name field on
the XYZ Templates form.
11. On the filter, create a Notify action.
a. Place the variable $Header Template$ in the Header field.
b. Enter other parameters as needed, for example, $Submitter$ as the user name,
relevant text (including request ID of the ticket), and so on.
The result of this filter is data-driven automatic template assignment workflow.
12. In the XYZ Incidents form, create a new ticket (for example, for Joe User) and assign it an
urgent value.
The filter workflow executes and creates a new ticket. This workflow will also create an
email 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 (see page 4673).
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 (see page 606).
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 (see page 1503).

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

Sending outgoing email in plain text (see page 1487)

Sending outgoing email in HTML (see page 1489)
Including attachments with outgoing email (see page 1492)
Displaying advanced options for outgoing email (see page 1494)
Determining message content of outgoing email (see page 1502)
Character sets in outgoing mail (see page 1503)
Adding extra custom headers to outgoing SMTP emails (see page 1503)
You can use the AR System Email Messages form to send outgoing email, as shown in the
following figure.


You can type the message, or specify content templates to use in the body of the email. To send
email from the Email Engine, you must use a specific label/value pair syntax along with the Action
label in the body of the email.
You can add the content from the From, To, Subject, etc. fields to the body of the email. You can
insert a string value of the field that you want to add on the AR System Email Messages form. For
example, if you want to insert the email address from the From field in the body of the email, you
must insert the #$18086$# variable, where 18086 is the ID of the From field.
You can include attachments with your email using the Attachments tab. From the Advanced
Options tab, you can use a template, substitute variables, or an alternate attachment as your body
content. (For information, see Displaying advanced options for outgoing email (see page ).)
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 (see page 2963).
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 (see page 604).)
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. 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 AR System Configuration Generic UI
form 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):
com.bmc.arsys.emaildaemon.SortMessages= false

To use the priority:
com.bmc.arsys.emaildaemon.SortMessages= true

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 (see page )
To add an attachment, see Including attachments with outgoing email (see page )
.
To send the email with a template other than the default templates for the specified
mailbox, see Using the Templates tab (see page 1494).
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 (see page 1496).
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 (see page 1485).
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 (see
page )
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 (see page ).
The Email Engine generates the email, as shown in the following figure.
An outgoing email in the HTML format

This outgoing email contains the following HTML input features:

Password control field — Users become nervous about sending passwords in clear
text. For security, this HTML message includes a Password control field as an input
type. When the user enters their password, the text is masked; asterisks appear
instead of the typed symbols or letters, as shown in the following figure.
A Password field with encryption

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 (see page 1519).
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 (see page 1493)

#Deleting an attachment (see page 1493)
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.
3. Click Delete Attachment to open the AR System Email Association form.

4. Close this form.
5. Click the Refresh Table button to refresh the table in the Attachments tab of the AR System
Email Messages form.
The attachment is deleted from the list.
Displaying advanced options for outgoing email

For outgoing messages, you can include advanced options like replacing variables. You can also
view information and error messagess of the outgoing message. To display the Advanced Options,
Message Information, and Errors tabs, perform the following tasks:
To display advanced options (see page 1494)

Advanced Options tab (see page 1494)
Using the Templates tab (see page 1494)
To add templates to outgoing email (see page 1495)
Using the Variable Replacement tab (see page 1496)
To replace a field value using a variable replacement (see page 1497)
Using the Attachment Alternatives tab (see page 1500)
To add an attachment alternative (see page 1501)
Message Information tab (see page 1502)
Errors tab (see page 1502)
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 (see
page 604).
To add templates to outgoing email
1. In the outgoing message, display the advanced options.

2. Click the Advanced Options tab, and then click the Templates tab.
3. Select templates from the relevant menu lists, or enter the name of a template as defined in
the AR System Email Templates form.
The AR System Email Messages form — Advanced Options, Templates tab
(Click the following image to expand it.)

Using the Variable Replacement tab

The Variable Replacement tab (the following figure) enables you to replace any variables in the
template with a value at the time of execution. This applies only to the specific outgoing email and
the templates specified in the Templates tab.
The AR System Email Messages form — Advanced Options, Variable Replacement tab

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.
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. 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 (see
page ). 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.

Adding a header (see page 1506)

Creating a result template for reply email (see page 1508)
Creating result templates for outgoing email (see page 1511)
Creating content templates for outgoing email (see page 1513)
Creating status templates for outgoing email (see page 1515)
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.
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 (see page ).
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 (see page )
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 (see page
686).
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 (see page ).
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.
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. 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 (see page )
.
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 (see page ).
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 (see page 1519).
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>

1.
<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 (see page ).
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
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 (see page 1521)

Sending a query instruction to the Email Engine (see page 1522)
Sending a Submit instruction to the Email Engine (see page 1528)
Sending a Modify instruction to the Email Engine (see page 1532)
Creating workflow to modify requests (see page 1543)
Searching for an entry to modify (see page 1550)
Displaying advanced options for incoming email (see page 1553)
Syntax for incoming email (see page 1555)
Syntax for variables in templates (see page 1556)
Character sets in incoming mail (see page 1557)

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.
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 (see page ).
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.
Limiting query results by using email qualifications (see page 1526)

Sending email query instructions using the Format label (see page 1527)
Entering field criteria using shorthand syntax (see page 1527)
To send a query
1. Create a new email message in your mail tool.

2. Address the email message to the incoming mailbox.
3.
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.

Home
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
(see page 1560).
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 (see page 1524)
) 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.
Supplying actual field values using keywords (see page 1530)

Specifying confirmation email field content using the Format label (see page 1531)
Including attachments with incoming email (see page 1531)
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 : 000000

000000001
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 (see page 629).)
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 (see page 1560).
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 (see page 1533)
Sending modify instructions in plain text (see page 1535)
Sending modify instructions in HTML (see page 1539)

Limitations to sending a Modify instruction (see page 1542)
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.
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 (see page 685).
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 (see page 1535)

Sending modify instructions in HTML (see page 1539)
Limitations to sending a Modify instruction (see page 1542)
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 (see page ).)
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 (see page 1537)).
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
(see page 626).)
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
(see page ).
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.

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

How to use workflow to modify requests (see page 1544)

Creating a security key (see page 1546)
Creating a sample form for your modify example (see page 1546)
Creating filter workflow that triggers a Notify action (see page 1546)
Exporting an email template (see page 1547)
Creating a submit email (see page 1548)
Replying to email notifications (see page 1548)
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 (see page 685).
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:
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 (see page 1569).
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 (see page ).
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.
5.
c. Click Finish.
6. Open the email template in a text editor.
Creating a submit email

Here you open a new email message and paste the contents of the exported mail template into the
new email. You use this email to submit a record to the Modify Email Workflow form.
To create a test email
1. Create a new email in your email client.

2. Address the email to the Email Engine inbox account.
3. Enter a subject line, for example, Modify Email Workflow.
4. Copy and paste the contents of the exported email template into the new email, and then
enter the required information for the template, for example:
#
# File exported Tue Sep 21 15:34:56 2004
#
Schema: Modify Email Workflow
Login: Demo
Password:
Action: Submit
Format: Short
Submitter !2!: Demo
Short Description !8!: Email Test*
Replying to email notifications

The email client sends your submit email to the incoming mailbox on the mail server. After
receiving the email from the mail server, the Email Engine parses the instructions in your email,
and makes the submit API calls to the AR System server. The server then creates a record in the
Modify Email Workflow form.
The incoming mailbox is configured to reply with results and generates an email response. Also,
when a record is submitted, filter workflow triggers a Notify action that includes instructions for
modifying the record.
The following procedure describes how you reply to email notifications generated by workflow.
To reply to email notifications
2.
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 (see
page 1551).
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 (see page 1550) 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 (see page ) 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 (see page ).
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.
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 ):

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

4.
# 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
Creating and using email templates

This section provides information and instructions about creating and using templates for outgoing
and incoming email.
Types of email templates (see page 1560)

Creating templates (see page 1563)
Exporting mail templates (see page 1563)
Using label-value pairs in templates (see page 1565)
Tips for using email templates (see page 1582)
Storing templates in the AR System Email Templates form (see page 1582)
Adding attachments to HTML templates (see page 1583)
Sending incoming email with user instructions (see page 1586)
Email template examples (see page 1592)
Preparing email templates after an upgrade (see page 1605)
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 (see page 1560)

User-defined instruction templates (see page 1562)
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, ensure 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 (see page 1580).)
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 (see page ) and Sending incoming
email with user instructions (see page ).
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 Yes No Schema Form label (see page
form. )
Server Server that will be affected by the Yes No Server label (see
instruction. page )
Login User name used when executing the Yes No User User Name Login, Password, and
instruction. Name Login TCP Port labels (see
page )
Password Password used when executing the Yes No Login, Password, and
instruction. TCP Port labels (see
page )
TCP Port TCP port used when logging in to the AR Yes No TCP
System server.

Label Description Incoming Outgoing Aliases Page
Login, Password, and

TCP Port labels (see
page )
RPC Number RPC number used when logging in to the Yes No RPC RPC Number and
AR System server. Authentication labels
(see page )
Authentication Authentication string used when logging Yes No RPC Number and
in to the AR System server. Authentication labels
(see page )
Language Language used when logging in to the AR Yes No Language label (see
System server. page )
Action Denotes the instruction to be executed. Yes No Instruction Action label (see
page )
Format Specifies the format of the information. Yes Yes Format label (see
page )
Qualification Qualification for a query-based instruction. Yes No Query Search Qualification label
(see page )
Result The name of the template to use in the Yes No Result Result Template label
Template reply. ResultTemplate (see page )
Status The name of the template to use when Yes No Status Status Template label
Template Status Information is returned. StatusTemplate (see page )
Header The template to be used as the header in No Yes Header Header Template and
Template the reply email. HeaderTemplate Footer Template
labels (see page )
Footer The template to be used as the footer in No Yes Footer Header Template and
Template the reply email. FooterTemplate Footer Template
labels (see page )
!Name! or !ID! The database name or ID of a AR System Yes Yes !Name! or !ID! labels
Form Field. (see page )
Key The key associated with a given sender or Yes No Encryption Key Key label (see page
user. Encryption )
Request ID The Request ID of the entry on which the Yes No Entry ID EntryID Request ID label (see
possible action must be executed. RequestID page )
Form label (see page 1567)

Server label (see page 1567)
Login, Password, and TCP Port labels (see page 1567)
RPC Number and Authentication labels (see page 1568)
Language label (see page 1568)
Action label (see page 1568)
Format label (see page 1570)

Qualification label (see page 1570)

Result Template label (see page 1571)
Status Template label (see page 1571)
Header Template and Footer Template labels (see page 1572)
!Name! or !ID! labels (see page 1572)
Key label (see page 1573)
Request ID label (see page 1573)
Label-value pair formats (see page 1573)
Global and local parameter declarations (see page 1576)
Variables (see page 1576)
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 (see page 609).)
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- An instruction that the administrator defines. The syntax is Action:adminDefinedText.

Defined

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 (see page ).
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 (see page 1357).)
For sample templates with Search (Query) actions, see Using templates with outgoing email (see
page ).
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 (see page 685).
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 (see page ) and Sending a
Modify instruction to the Email Engine (see page ).
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 (see
page ).
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 (see page )) 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 (see page 1600) 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 (see page ).
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 (see page 1580).)
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 (see page 687).
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 (see page 1573)

XML format (see page 1574)
HTML format (see page 1574)
Text field (see page 1575)
Radio buttons (see page 1575)
Checkbox buttons (see page 1575)
Menu field (see page 1576)
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 (see page 1511).
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 (see page
).
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 (see page ).
Variables
In this topic:
Variable examples (see page 1578)

Using variables with notifications (see page 1578)
Date formats supported in email templates (see page 1579)
Reserved variables (see page 1580)

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 (see page 1573).
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 (see
page 1578).
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 (see page 1500).
2.
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 (see page 1496).
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 (see page 1562).
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.
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 (see
page 1583).
Adding attachments to HTML templates

Managing HTML template attachments (see page 1585)

Exporting templates with attachments to another server (see page 1586)
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 (see page 1585)

To modify an attachment (see page 1585)
To add a previously saved attachment to your template (see page 1585)
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 (see page 1583)).
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

Creating and storing a template for use with user instructions (see page 1588)
Creating user instructions (see page 1589)
Sending a user instruction in an incoming email (see page 1590)
Results of the user instruction (see page 1591)
Using variables with user instructions (see page 1592)
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 (see page 1577) 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.
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 (see page ).
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 (see page ).)
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.
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.
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.
Creating email templates to search for Request ID (see page 1593)

Creating email templates to search for fields (see page 1594)
Creating email templates to perform searches using qualifications (see page 1594)
Creating email templates that include attachments (see page 1595)
Email content template with Submit and Query actions (see page 1597)
Email reply using result templates in HTML format (see page 1598)
Sample HTML result template (see page 1600)
Email status template in HTML format (see page 1602)
Header and footer templates (see page 1603)

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

2.
# 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 (see page 1508).
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
(see page ). 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 (see page )
.

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 (see page ).
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 (see page ).
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 (see page ).
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 (see page ). 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 (see page ).
For more information, see Header Template and Footer Template labels (see page ).

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 (see page 629).
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 (see page
).
Email Engine forms

The Email Engine provides a set of administration, user, and workflow forms for configuring and
processing email from your mail server.
Email Engine administration forms (see page 1606)

Email Engine user forms (see page 1614)
Email Engine workflow forms (see page 1622)
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 (see page 1606)
AR System Email Mailbox Configuration form (see page 1607)
AR System Email Templates form (see page 1611)
AR System Email User Instruction Templates form (see page 1612)
AR System Email Error Logs form (see page 1612)
AR System Email Security form (see page 1613)
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 (see page
1462).
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
Name/IP mentioned on this form.
Important
The Email Engine does not resolve the mail server if either Mail Server Name/IP or
Failover Mail Server Name/IP contains a new line character. You should use either the
server name or the IP address in both fields. If you use the server name in one field and
the IP address in the other, an error message is displayed and you are not allowed to
save the form. You should use similar naming conventions for both the AR System Email
Configuration form and the AR System Email Failover Mail Server form. You should not

provide the IP address in one form and the server name in the other. If you use different
naming conventions in these forms, no error is displayed, but the failover mail server is
not used successfully if the primary mail server stops working.
AR System Email Mailbox Configuration form

In this topic:
Incoming mailbox--Basic and Advanced Configuration tabs (see page 1607)

Outgoing mailbox--Basic and Advanced Configuration tabs (see page 1609)
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 (see page 604) and Configuring
incoming mailboxes (see page 627).
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.
Basic Configuration tab
Email Select the email protocol. Incoming mailboxes include following protocols: For 32-bit JVM:
Server
Type 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
Interval mailbox.
(Minutes)
Enables the secure socket layer. Used only with POP3 and IMAP4.

Email
Server
Requires
SSL
Inbox Path Enter the full path file name to the mbox file corresponding to the user email account that will be used. Used only
with MBOX.
Email Enter the name or IP address of the mail server used in your organization. Used only with POP3 and IMAP4.
Server
Name/IP
Email Enter the port used for connecting to the mail server. The default port number is determined by the protocol
Server Port selected and whether Secure Sockets Layer (SSL) is selected. Used only with POP3 and IMAP4. If you do not
enter a port number, the following default values will be used:
POP3: 110
POP3 with SSL: 995
IMAP4: 143
IMAP4 with SSL: 993
Email Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
Server
User
Email Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
Server
Password
Profile Enter the name of the Microsoft Exchange profile to be used for incoming mailbox. Used only with MAPI.
Name
Advanced Configuration tab
Associated Enter the name of an outgoing mailbox used to reply to incoming emails that require a response.
Mailbox
Name
Email Select Parse to enable the Email Engine to detect and process instructions included in an incoming email
Action message, or accept the default value of None for no action.
Use Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (BMC
Original Remedy Mail Server release 5.1 or earlier) and thus ignore special HTML fields and XML formats.
Template
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
Result be included.
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
Workflow message if no 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.
Default This action will confine all instructions received by this mailbox to the specified form.
Workflow
Form
Use Select Yes to force a security key to be used for incoming mail to this mailbox.
Security
Key
Use Select Yes to use AR System server login information that might be included within the incoming email message.
Supplied
User
Information
Use Email 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 Select whether mailbox is Incoming or Outgoing.

Function
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: For 32-bit JVM:
Type
SMTP
MAPI
For 64-bit JVM:
SMTP
Polling Enter the number of minutes after which the Email Engine will check for new outgoing mail waiting to be sent
Interval 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 Enter the port used for connecting to the mail server. The default port number is determined by the protocol
Port selected and whether Secure Sockets Layer (SSL) is selected. Used only with SMTP. If you do not enter a port
number, the following default values will be used:

SMTP: 25
SMTP with SSL: 465
Email Server Enter the user name of the administrator or user for this email account. Used only with SMTP.
User
Email Server Enter the user name of the administrator or user for this email account. Used only with SMTP.
Password
Profile Name Enter the name of the Microsoft Exchange profile to be used for the outgoing mailbox. Used only with MAPI.
Advanced Configuration tab
Associated Enter the name of the incoming mailbox that will be used to receive instructions or notifications.
Mailbox Name
Default Select Yes so that all outgoing messages for which an outgoing mailbox is not specified will be sent using
Outgoing information in this entry.
Mailbox
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 Enter the Reply-to email address for the mailbox owner or administrator, if you plan to enable users to reply to
Address notification messages sent from this mailbox.
Organization For email clients that display an organization name, enter the name of the mailbox owner, or administrator's
organization.
Delete Select Yes to have outgoing notification messages deleted from the AR System Email Messages form after
Outgoing they have been sent from this mailbox.
Notification
Messages
Default Enter the email addresses to send to if addresses have not been specified in the Messages tab for a notify
Addressing filter or escalation.
Default To Enter the default email addresses for those who should receive outgoing messages from this mailbox.
Default CC Enter the default email addresses for those who should receive copies of outgoing messages from this
mailbox.
Default BCC Enter the default email addresses for those who should receive blind copies of outgoing messages from this
mailbox.
Default If a user creates a message without specifying a template in the Templates tab for either Notify filter or
Templates escalation actions, then this template will be used by default.
Header Enter the template to be used as the default header template.

Template
Footer Enter the template to be used as the default footer template.

Template
Status Enter the template to be used as the default status template.

Template
Result Enter the template to be used as the default result template.

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 (see page
1582).
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
Name attach a new file, then click inside the field. You can edit the name as needed. After saving your template, the AR
System Email Templates form uses data-driven workflow to populate menus in the Email Engine forms that use
templates, for example, when you add an email template to a Notify action.
Description (Optional ) Enter the description of the template.
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
Attachment example, HTML file 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
Attachment template will not be 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)
Click to refresh the table after you have added, modified, or deleted an attachment.

Refresh
Table
button
(HTML
templates
only)
Add Adds an existing attachment to the template.

Existing
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 (see page 1586).
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 (see page 4383).
Fields on the AR System Email Error Logs form

Log Message ID Message ID and date on which error was created.

and Create Date
Mailbox ID Number of the message to which the log applies.

Number
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 (see page 604) and Configuring incoming mailboxes (see page 627).
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 (see page 687).
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
Addresses becomes enabled.
Email Addresses Option that verifies incoming messages from a set of specific email accounts using a security key.

Note
To configure multiple email address for a single security key, you must separate the email
addresses with a semicolon (;).
Expiration Date Expiration date for this security key. After the key expires, you can either modify the expiration date in
this form, or set the Expires field to No.
Description Description for the key, such as why it was created or instructions for modifying or deleting it.
Email Engine user forms

This section contains information about the user forms available with the Email Engine:
AR System Email Messages form (see page 1614)

AR System Email Error Messages form (see page 1617)
AR System Email Attachments form (see page 1621)
AR System Email Attachment Join form (see page 1622)

In this topic:
Message tab (see page 1615)

Attachments tab (see page 1615)
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 (see page 1464).
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 With qualification variables, any access information necessary.
Port
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 pool) attachment, instead of typing it into the Body field in the Message tab.
Plain Text Content Language encoding used.

Attachment Encoding
HTML Content Language encoding used.

Attachment Encoding
RTF Content Language encoding used.

Attachment Encoding
Values Attachment Language encoding used.

Encoding
Fields on the AR System Email Messages form — Message Information tab
Message ID The unique value that identifies the message.
Date The date on which the message was sent; this value is retrieved from the Date header of the incoming message.
Received
Date Sent The date on which the message was sent; applicable to outgoing messages only.
Execute The timestamp of when the incoming message was executed, or when the outgoing message was sent.
/Send At
Parse The parsing status of the message; applicable to incoming messages only. The options and their meanings are:
Message
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 The sending status of the message; applicable to outgoing messages only. The options and their meanings are:
Message
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 Num The error message number.

ber
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:
Copying incoming messages to the AR System Email Messages form (see page 1618)
To copy the rectified incoming messages to the AR System Email Messages form
(see page 1618)
Enabling the Clean AR System Email Error Messages escalation (see page 1618)
Message tab (see page 1619)
Attachments tab (see page 1619)
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.
1. Go to Escalation > Execution Options.

2. Change the value of the State field to Enabled.
3. (Optional) Change the Escalation period in accordance with your requirements from the
default value of 15 days.
Note
Additional conditions can be set using the Run Process field.
4. To clean up the system logs, restart the BMC Remedy Email Engine.
All the messages in the AR System Email Error Messages form will be deleted depending
upon the conditions set in the escalation. For each message, this form provides the name of
the mailbox from which the message was generated, the message type, name and
organization of the mailbox owner; names of recipients sent to and copied; the text of the
message (in HTML, plain text format, or a combination of both); and (under a separate tab)
a list of any attachments included with the message.
Fields on the AR System Email Error Messages form
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 With qualification variables, any access information necessary.
Port
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 pool) attachment, instead of typing it into the Body field in the Message tab.
Plain Text Content Language encoding used.

Attachment Encoding
HTML Content Language encoding used.

Attachment Encoding
RTF Content Language encoding used.

Attachment Encoding
Values Attachment Language encoding used.

Encoding

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

Name
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 (see page 1622)

AR System Email Instruction Parameters form (see page 1622)
AR System Email Association form (see page 1623)
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
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
Setting up the approval process

The following topics provide information about how to set up an approval process:
Approval Server concepts (see page 1624)

Defining an approval process (see page 1657)
Defining approval rules (see page 1668)
Using the Lunch Scheduler sample application (see page 1706)
Approval forms (see page 1713)
Running the approval utilities (see page 1791)

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 (see page 1624)

Approval roles (see page 1625)
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 (see page ).
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 (see page
).

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 (see page ).) 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 (see page ) 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 (see page 1626)

Approval processes (see page 1629)
Approval rules (see page 1640)
Approver fields (see page 1655)
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 (see page 1627)

Approval server supporting forms (see page 1627)
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. (see page 596)
Approval server supporting forms

In this topic:
Approval Central (see page 1628)

Detail form (see page 1628)
Signature form (see page 1628)
Detail-Signature form (see page 1628)
Approval request form (see page 1628)
Three-way join form (see page 1628)
More Information form (see page 1629)
Signature authority form (see page 1629)
Application Pending form (see page 1629)
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 (see page 3001) and Administration forms (see page ). This section introduces
some of the basic forms for ease of reference.

Approval Central
See Overview of Approval Central. (see page 1024)
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 (see page 3003). For general information about join forms, see Join
forms (see page 2375).
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 (see page 1630)

Approval process stages (see page 1630)
Approval process types (see page 1632)
Summary of process types (see page 1637)
Creating signatures for multiple approvers (see page 1637)
Associating an action date for a process or signature (see page 1638)

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 (see page )
.
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 (see page ).
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 (see page ).) 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:
Parent-Child process (see page 1632)

Level process (see page 1634)
Ad Hoc process (see page 1635)
Rule-Based process (see page 1637)
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 (see page ). For information about rules and how they are used with each
process type, see Approval rules (see page ). For information about creating rules, see
Defining approval rules (see page ).
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 (see page ).
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 (see page ).
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 (see page ).
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 (see page 1645).

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 (see page 2533).
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 Routing method Determining next approver

type
Parent- Hierarchy of individuals. The process Get Next Approver and Parameterized Get Next Approver rules
Child administrator defines the relationships between determine the relationship of the next approver to the current
individuals. owner.
Level Hierarchy of organizations. The process Get Next Approver and Parameterized Get Next Approver rules
administrator defines the levels and their determine the next level and approvers.
members.
Ad Hoc Routing is based on the approvers entered by Determined manually by users.

the requester or approvers.
Rule- Custom, as determined by the process Determined by the Process Administrator. Parameterized Get
Based administrator. Next Approver rules can add approvers.
Creating signatures for multiple approvers

An approval request can be assigned to multiple approvers. Administrators can specify how to
manage responses to such a request at the process, rule, or role level. Administrators use the If
Multiple Approvers setting for this purpose.
The options are:
One Must Sign — Creates a single signature entry for all the relevant approvers. Only one
of the approvers needs to take action.

All Must Sign — Creates a separate signature entry for each approver. All approvers must
take action for the request to proceed further.
(Process-level only ) Allow Only One Approver — Creates a single signature entry for an
approver. If a requester specifies multiple approvers for a request, the approval server
returns an error.
Associating an action date for a process or signature

In this topic:
How the action date for a Parent-Child or Level process is calculated (see page 1639)
How the action date for an Ad Hoc process is calculated (see page 1639)
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 (see page 1764).
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 (see page 2903).
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 (see page 1660).
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 (see page 1660).
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 (see page 1641)

Next Approver stage (see page 1644)
Approver Response stage (see page 1647)
Completion Check stage (see page 1652)
Process Done stage (see page 1654)
Chained processes (see page 1655)
Self Check stage

In this topic:
Auto Approval rules (see page 1642)

Self Approval rule (see page 1643)

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 (see page ).
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 (see page )
.
Note
A third type of get authority rule, called Get Authority Regular, is performed only during
completion processing. See Get Authority rules (see page 1641) and Get Authority
Regular rules (see page 1641).
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 (see page ).
Next Approver stage

In this topic:
Get next approver automatically (see page 1644)

Get next approver manually (see page 1645)
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 (see page ).
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
(see page ).

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 (see page ).
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 (see page 1635).
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 (see page ).
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 (see page ).
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 (see page ).
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
(see page ).
The following figure illustrates how rules and ad hoc approver entries are used in the Next
Approver stage of an approval process.
Get Next Approver rules


Note
Process administrators should set up notifications to indicate when an erroneous ad hoc

selection is waiting for correction.
Approver Response stage

In this topic:
Signature Accumulator and Statistical Override rules (see page 1648)

Signature Accumulator rules (see page 1649)
Statistical Override rules (see page 1649)

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 (see page 1652).
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 (see page 1697). To create a Signature Accumulator rule, see Defining
Signature Accumulator rules (see page ).
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 Signatures Approving requests Rejecting requests

type considered
Level Only signatures for Preempts the approval server to proceed Preempts the approval server to reject the
the current level to the next level. request and stop the processing.
Parent- All signatures, at all Preempts the approval server to proceed Preempts the approval server to reject the
Child times to proceed to next parent. request and stop the processing.
Ad Hoc All signatures, at all Preempts the approval server to approve Preempts the approval server to reject the
times the request. request and stop the processing.
Rule- All signatures, at all Preempts the approval server to proceed Preempts the approval server to reject the
Based times to the next set of approvers. request 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
To create Statistical Override rules, see Defining Statistical Override rules (see page ).
Completion Check stage

In this topic:
Example of Completion rules (see page 1652)

Get Authority and Get Authority Regular rules (see page 1652)
Completion rules (see page 1653)
Examples of the routing completion check (see page 1653)
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 (see page 1652)
and Get Authority Self rules (see page 1652).

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 (see page ). 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 (see page ).

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 (see page ).
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 (see page 1655)

Approval Change Schema utility (see page 1656)
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
AP:
PreviewSignatures
13207 Approvers
AP:Signature
AP:
PreviewSignatures
AP:PreviewInfo
14511 GNA Approvers

AP:Signature
14512 PGNA Approvers

AP:Signature

Field ID Field name Form name
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
(see page 1656).
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 8000
SQL 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 (see page 1791).
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.
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 (see page 1658)

Creating a process (see page 1658)
Working with existing processes (see page 1664)
Defining roles (see page 1667)

Using the Process tab on AP-Administration

To create and manage processes, use the Process tab on the AP:Administration form. When you
select the Process tab, a table field appears. To populate the table with all existing processes, click
Refresh. You can sort this list on any column, including the process name, the linked approval
request form, the process type, the process status (active or inactive), or the process ID. If you
installed the sample applications, all the sample application processes appear on this list.
The buttons on the Process tab take the following actions:
View — Opens the AP:Process Definition form for the selected rule in Modify mode. You
must select a process from the list to use this button. Use this option to view and modify
existing processes.
Search — Opens a blank AP:Process Definition form in Search mode. Use this option to
search for a process using a field that does not appear in the processes list.
Create — Opens the AP:Process Definition form in New mode. Use this option to create a
new process.
Delete — Deletes the selected process. You must select a process from the list to use this
button.
Refresh — Refreshes the current list of processes. Use this button to refresh the list, for
example, after adding a new process.
Creating a process
Creating More Information escalations (see page 1659)

Creating signature escalations (see page 1660)
Defining process basics (see page 1662)
Setting process intervals (see page 1663)
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 (see page 1743).
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 (see page
).
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 (see page
3007).
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 (see page
).
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 (see page 1374).
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.
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.
Scenario:
After an employee submits his expenses in the Expense Management System, the manager is
notified. The request status is set to Submitted.
The desired approval schedule is two days. This must include only business working days and
exclude weekends and holidays. If a request is submitted on a Friday, the manager is expected to
approve the request by the following Monday. If Monday happens to be a holiday, the manager can
approve the request by Tuesday. These calculations are based on the organization's business
calendar and holiday calendar.
In addition, you can set the time past which the request will change its status automatically. In our
example, the status is set to Approved. If the approval request is outstanding for more than two
days, the request is auto-approved and employees will be reimbursed their expenses.
The primary feature of signature escalations is notifying the approver about the outstanding
approval. This can be implemented in the following situations:
The interval when the submitted request is auto-approved is considerably long. For
example, if the time when the request is auto-approved is 10 days, you would want to keep
notifying the manager until that time.
The changed state is set to a status between Submitted and Approved statuses. For
example, if the approval request is outstanding, the status is set to pending after two days.
The manager is kept notified about the pending request.
Auto-approval is not implemented. All approvals require express approval from the
manager.
Successive notifications can be set at the frequency based on the first notification. If the first
interval is set to 3 days, the manager receives the first notification on Wednesday for the request
submitted on Friday last. If we set the repeat frequency to 1 day, the manager receives the second
notification on day 4 (Thursday), the third on day 5 (Friday), and so on.

The notification feature can be set to include various conditions prior to approval or completion,
such as:
pending action
error or invalid state
process put on hold
when requesting more information
The following 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 (see page
).
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 (see page 1374).
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.
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 (see page 1783) and Approval Central
(see page ).
6. To send notifications when a signature line has been outstanding (in any state) for too long,
specify the Notification: Still <OutstandingState> parameters. For example, If a signature
line has been outstanding in Pending state for too long then specify the Notification: Still
Pending parameters.
a. Enter a number in the First Interval field to indicate when you want the first
notification sent, and select the item that this number represents from the Unit list.
b. If you want a second notification sent, enter a number in the Repeat Interval field
and select the item that this number represents from the Unit list.
This is shown on the Approval Central > Past Due requests > Action Date column.
For more information, see Approval Central (see page ).
7. If you want to send notifications when the approval request remains in a certain state
(Pending, Error, Hold, or More Information) too long, specify the Notification: Still <in
State> parameters. For example, if a signature line has been outstanding in Hold state for
too long then specify the Notification: Still Hold parameters.
a. Enter a number in the First Interval field to choose the state that indicates when you
want the first notification sent, and select the item that this number represents from
the Unit list.
b. If you want a second notification sent, enter a number in the appropriate Repeat
Interval field and select the item that this number represents from the Unit list.
Defining process basics

Use the Basic tab on AP:Process Definition to define basic information such as the process name
and type, the associated form, and approval success criteria.
To create a process
1. Open the AP:Administration form.

See Working with the AP-Administration form (see page 596).
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 (see page 1743).
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 (see page ) and AP-Process Definition
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 (see page 1664)

To delete a process (see page 1664)
To rename an approval process or form (see page 1665)
To view and modify a process
1. Open the AP:Administration form. See Working with the AP-Administration form (see page
596).
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 (see page ) 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. 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 (see page 596).
2. Click Rename in the navigation pane.
The Approval Server Rename dialog box (AP:Admin-Rename form) appears as shown in
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

7.
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 (see page
596).
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.
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 (see page ).
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.
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 (see page 1669)

Creating a rule (see page 1669)
Approval rule definitions and examples (see page 1676)
Working with existing rules (see page 1704)

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 (see page 596).
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
Using the Basic tab on the Rule Definition form (see page 1670)
Using the Set Fields tab on the Rule Definition form (see page 1672)
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 (see page ).
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 (see page ) and Defining Parameterized Get Next
Approver rules (see page ).
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.
2. In the Rule Name field, enter a name for the rule.

Rule names must be unique and can be as long as 30 characters. For ease of
administration, use a rule name that reflects the application or process, the rule type, the
rule function, or some combination.
3. In the For Process field, select the process name that this rule will support from the list.
The processes that appear on this menu are those you have defined in the Process tab.
When you select the process name, BMC Remedy AR System automatically populates the
Process Instance ID field.
4. In the Rule Type field, select the appropriate rule type from the list. For example, if you are
creating a Get Next Approver rule, select Get Next Approver.
When you select a rule type, the Rule Definition form changes to display the fields
appropriate for the rule type. Fields that apply to the rule type have a white field box. Fields
that do not apply are gray.
5. In the Order field, enter an execution order number. The default value is "0."
This number determines the rule sequence when two or more of the same rule type exist for
a specific process.
6. In the Status field, select either Active or Inactive. The default value is Active.
Inactive rules do not run when the process runs. While you are developing a set of rules for
a process, it might be helpful to use the Inactive status. When you are ready to test your
rules, change the Status field to Active.
Note
If you save a rule with the Status field empty, the rule is saved as Active.
7. In the Assignee Group Permissions field, the Public group appears by default. If you use
this field for multi-tenancy support, create workflow to populate this field with the correct
assignee group name. You do not need to change this setting when creating the rule.
The approval server supports multi-tenancy for use by application service providers. The
Assignee Group Permissions field is field 112, and appears on all the approval server
forms. The field 112 value from records created in the AP:Details form is used automatically
in all the other approval server forms, for example, AP:Signature, AP:More Information, and
so on.
8. 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 (see page ). 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 (see page 2722).
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 (see page 1677)

Defining all Get Authority rules (see page 1678)
Defining Self Approval rules (see page 1681)
Defining Prep Get Next Approver rules (see page 1682)
Defining Get Next Approver rules (see page 1684)
Process type and Get Next Approver rules (see page 1685)
Creating a Get Next Approver rule (see page 1686)
Defining Parameterized Get Next Approver rules (see page 1688)
Defining Validate Approver rules (see page 1692)
Defining Signature Accumulator rules (see page 1694)
Defining Statistical Override rules (see page 1696)
Defining Completion rules (see page 1702)
Defining Approval Process Done rules (see page 1703)

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 (see page ).
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 (see page 1677)

Example of an Auto Approval rule (see page 1677)
To define an Auto Approval rule
1. Follow the procedure in Using the Basic tab on the Rule Definition form (see page )to
complete the basic information about the rule.
Select Auto Approval in the Rule Type field.
Write a rule condition to test for a specific field value from the approval request form,
for example, checking whether the value for an Estimated Total field is less than
$15.00.
2. (optional) Enter an Audit Text message.
This message is written to the audit log when the condition for this rule passes. The audit
text can include embedded field references that are filled when the rule condition passes. If
you do not enter an audit message, a default message is written to the audit log.
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 (see page 1679)

Example of a Get Authority rule (see page 1680)
To define any type of get authority rule
In the Rule Type field, select Get Authority, Get Authority Self, or Get Authority
Regular.
Create a condition statement in the Run If field if necessary. The condition statement
controls whether the rule actions execute. This field is optional for this rule type; if no
qualification exists, the rule always runs.
2. Click the Set Fields tab.
3. In the Set Field Type field, select an action from the menu.
The Set Field Type indicates the type of assignment to be used for the rule action. See
Using the Set Fields tab on the Rule Definition form (see page ).
4. In the From Form field, select a form name from the menu.
This value defines the form that the rule will search for the requested data; for example, the
AP-Sample:Signature Authority form.
5. In the On Server field, select the server where the form is located.
Current — The form exists on the current server.
Alternate — The form exists on another server. In this case, type the remote server
name in the Server field.
6. In the Qualification area, enter a qualification statement to define the parameters for
retrieving the authority data.
For example, to retrieve the current approver's signature authority limit from the AP-Sample:
Signature Authority form, define a qualification statement that sets $Approver$ (current
approver) to equal the Login Name field in the Signature Authority form.
Click Fields from the Set Fields Form to select the Login Name field from the form
named in the From Form field.
Click Fields from Application Form to select the $Approver$ field from the current
record of the AP:Signature form.
7.
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 AP-Sample:Signature Authority form.
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 (see page ) to
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
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 (see page ).
b. If the action type is Query, select a form name from the From Form list. This value
indicates which form to search for the data being retrieved by the query.
c. In the On Server field, select Current if the form exists on the current server, or select
Alternate if the form exists on another server, and enter the server name where the
form is located in the Server field.
d. Depending on the action type, enter the qualification statement or command line in
the Qualification area.
e. In the Fields Data area, enter the name of the field or fields to receive the data in the
Field Name column, and a value statement or the name of each source form field in
the Value column.
f. Click Save.
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 (see page 1685)

Get Next Approver rules in a Level process (see page 1685)
Get Next Approver rules in a Rule-Based process (see page 1686)
Ad Hoc processes (see page 1686)
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 (see page 1632) 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 (see page 1634) 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 (see page 1637).
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 (see page 1635).
Creating a Get Next Approver rule

To create a Get Next Approver rule, use the following procedure.
To define a Get Next Approver rule (see page 1686)

Example of a Get Next Approver rule (see page 1687)
To define a Get Next Approver rule
Select Get Next Approver from the Rule Type list.
The rule condition in the Run If text box is optional. Use this field to define a
conditional statement that controls whether the rule executes.
2. In the If Multiple Results field, select a value from the menu.
This field determines what occurs when more than one row of data is returned by the Get
Next Approver rule. The following choices are available:
Value from First — Uses the value from the first record retrieved.
Values from All — Uses all of the values retrieved.
Return Error — Returns an error message if more than one record is retrieved.
Clear — Leaves this field blank.
3. In the If Multiple Approvers field, select a value from the menu.
This field value determines the signature requirements when more than one approver is
returned by the Get Next Approver rule.
One Must Sign — A single signature record is created and only one of the approvers
listed in the record is required to act upon the approval request to consider the record
complete.
All Must Sign — A separate signature record is created for each individual in the
approver list, including individuals within a role. In this case, all of the approvers
retrieved by the Get Next Approver rule must act upon the approval request.


4. In the Next Approver Rule Is field, select a value from the menu.
This field value determines how the approver list is constructed when multiple Get Next
Approver rules exist in the process. It is often used in a Rule-Based process that uses set of
Get Next Approver rules to build an approver list.
Additive — Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, and further rules are to be processed.
Ending — Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, but no further rules are to be processed.
Exclusive — Indicates that this rule assigns the entire approver list, and no further
rules are processed. In addition, if a previous rule created an approver list, that list is
ignored.
5. (optional ) Enter the rule condition in the Run If text box.
If used, this field defines a conditional statement that controls whether the rule runs. You
can type the conditional statement or you can build it by using the qualification bar and list.
See Building qualifications and expressions (see page 2748).
7. In the Set Fields Type field, select the appropriate action type. See Using the Set Fields tab
on the Rule Definition form (see page ).
8. For a query, select a form name from the From Form menu.
This value indicates in which form to search for the query.
10. Depending on the action type, enter the qualification statement or command line in the
Qualification area.
11. In the Fields Data area, enter the name of the field or fields to receive the data in the Field
column.
12. Click Save.
Example of a Get Next Approver rule

The following figure illustrates an example of a Get Next Approver rule for the Parent-Child process
in the Lunch Scheduler sample application.
The Basic tab in this example does not contain a Run If statement, so the rule always runs. The If
Multiple Approvers setting causes the approval server to create a single signature record for the
approver list (One Must Sign). Therefore, only one approver action is required for the approval
request to be complete. The Next Approver Rule Is field is set to Ending, so no other Get Next
Approver rules will be processed after this one.

On the Set Fields tab, the Qualification statement causes the approval server to match the current
approver ($Approver$) to the Login Name field in the AP-Sample:Signature Authority form during
the query. The current approver could be the approval request submitter or an approver.
The rule retrieves the "parent" of the current approver by getting the value from the $Manager
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 (see page 3021).
For example, an approver using the preview feature in a Parent-Child process might see the
following hierarchy of approvers:
1. Allan
2.
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 (see page 2903).
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 (see page 1689)

Example of Parameterized Get Next Approver rule (see page 1690)
To define a Parameterized Get Next Approver rule
Select Parameterized Get Next Approver from the Rule Type list.
The Run If condition is optional. Use this field to define a conditional statement to
control whether the rule runs.
2. In the If Multiple Results field, select a value from the menu.
This field determines what occurs when more than one row of data is returned by the Get
Next Approver rule. The following choices are available:
Value from First — Uses the value from the first record retrieved.
Values from All — Uses all of the values retrieved.
Return Error — Returns an error message if more than one record is retrieved.
3. In the If Multiple Approvers field, select a value from the menu.
This field value determines the signature requirements when more than one approver is
returned by the Get Next Approver rule.

One Must Sign — A single signature record is created and only one of the approvers
listed in the record is required to act upon the approval request to consider the record
complete.
All Must Sign — A separate signature record is created for each individual in the
approver list, including individuals within a role. In this case, all of the approvers
retrieved by the Get Next Approver rule must act upon the approval request.
4. In the Next Approver Rule Is field, select a value from the menu.
This field value determines how the approver list is constructed when multiple Get Next
Approver rules are included in the process.
Additive — Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, and further rules are to be processed.
Ending — Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, but no further rules are to be processed.
Exclusive — Indicates that this rule assigns the entire approver list, and no further
rules are processed. In addition, if a previous rule created an approver list, that list is
ignored.
5. Select Yes or No from the Guaranteed Add list.
Yes — The parameterized rule runs even when a Completion rule would otherwise
determine that the process is done, thus guaranteeing that the user will be added as
an approver.
No — If a Completion rule determines that the conditions exist for the process to be
done, the process does not return to the Get Next Approver stage to run this rule.
8. For a query, select a form name from the From Form menu. This value indicates in which
form to search for the query.
Alternate — The form exists on another server. In this case, type the server name
where the form is located in the Server field.
Qualification area.
column.
12. Click Save.
Example of Parameterized Get Next Approver rule

The following figure illustrates an how an example Parameterized Get Next Approver rule
operates. The example rule includes the following settings:
Run If qualification: $Level$ = "%1"

Guaranteed Add: Yes
Set Fields: $Next Approver$ = "%2"
Example of a Parameterized Get Next Approver rule
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.
3. The approver uses functionality added to the approval request form, such as a button that
opens an "Add Approvers" form, to enter the level and the approver name. When the
approver saves his or her changes, a filter runs that captures these values and sends an
Add-PGNA-Values application command using the values to the approval server.
For example:
*Application-Command Approval Add-PGNA-Values -o "My Param Rule" -l "4/Michel

LeTourneau" *
4. The approval server receives the command, and stores the data in the Param Data field on
the AP:Detail record.
5. After the approval server runs the Get Next Approver rules, it runs Parameterized Get Next
Approver rules. While running the parameterized rules, it retrieves the values from the
Param Data field in the detail record. In this case, it retrieves 4/Michel LeTourneau and
parses this into %1="4" and %2="Michel LeTourneau"
6. The approval server replaces the variables in the Parameterized rule with these values:
Run If qualification — $Level$ = 4
Set Fields — $Next Approver$ = "Michel LeTourneau"
7. If the condition matches, the Set Fields action is executed. If the condition never matches
and the regular Get Next Approver rules do not return any approvers, the approval server
checks for the Guaranteed Add flag. If this is set to yes, the parameterized rule executes,
even though the Run If condition is not satisfied.
Parameterized Get Next Approver rules are executed when a preview is generated, so the added
approver is visible when future approvers preview the request.
Defining Validate Approver rules

A Validate Approver rule enables you to verify approver names when they are manually entered on
an approval request. This applies to either an Ad Hoc process type or an ad hoc override.
This rule validates the approver name at the time of entry by searching for a match to the entered
name on a specified form, for example, a signature authority form such as AP-Sample:Signature
Authority in the sample application.
You can define any number of Validate Approver rules. This allows you to search more than one
form to validate an approver name. This topic includes the following information:
To define a Validate Approver rule (see page 1693)

Example of a Validate Approver rule (see page 1693)
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 (see page 2533).
To define a Validate Approver rule
Select Validate Approver from the Rule Type list.
The Run If condition is optional. Use this field to define a conditional statement to
control whether the rule runs.
Alternate — The form exists on another server. Enter the remote server name in the
Server field.
Qualification area.
column.
8. Click Save.
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
To define Signature Accumulator rules (see page 1695)

Example of a Signature Accumulator rule (see page 1695)
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
Select Signature Accumulator from the Rule Type list.
Use the Run If qualification to include or exclude signatures. The Run If condition is
qualified on each signature, for example:
$Approval Status$ = "Approved"
If the Run If condition is met, the server will perform the Set Fields operation.
6. Enter a qualification statement to define the parameters for retrieving the authority data.
For example, to retrieve the current approver's signature authority limit, define a qualification
statement that sets $Approver$ (the current approver) to equal the user name field on the
signature authority form (such as Login Name on AP-Sample:Signature Authority).
column.
8. Click Save.
Example of a Signature Accumulator rule

The Get Agreement sample application includes an integrated set of Signature Accumulator and
Statistical Override rules in an Ad Hoc process. See Example of decision-making rules in a sample

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 (see page 1696)

Example of decision-making rules in a sample application (see page 1697)
To change the rules to active status (see page 1697)
To create a request that activates the example rules (see page 1699)
To observe the approval process in the AP:Detail-Signature form (see page 1700)
Example of a Statistical Override rule with default data (see page 1701)
To define a Statistical Override rule
Select Statistical Override from the Rule Type list.
In Statistical Override rules, the Run If condition specifies the condition to be
evaluated. For example, to check if 50 percent or more of the signatures have been
approved, you create a Run If condition as follows:
$Total Signatures$ / $Total Approved$ >= . 5
To derive the statistical override value, you can use static values, arithmetic
operations, keywords, the results from functions, and values from the record that the
approval server is processing in the AP:Detail-Signature form.
3. In the Set Fields Type field, select the appropriate action type.
See Using the Set Fields tab on the Rule Definition form (see page ).
5. In the On Serverfield, select the server where the form is located.
6. Enter a qualification statement, if any.
7. In the Fields Data area, type one of the following values (or its integer equivalent) into the
first entry in the Valuelist:
Approved

Rejected
In a Statistical Override rule, the Field column on the Set Fields tab is automatically
populated with the statistical override field name. The Set Fields function sets the
specified value in the statistical override field on the Detail form. The only valid
statistical override values are Approved or Rejected.
8. Click Save.
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 (see page ).
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.
3. In the Summary field, type:

I want to purchase a new laser printer.
4. In the Details field, type:
A really nice new laser printer costs $600.
This entry is only a comment, and does not affect the behavior of the rule.
5. In the Initial Approvers field, type:
Jack Miller; Larry Goldstein; Violet Anderson
Make sure to type a semicolon between each approver's name.
6. Click Save. To illustrate how statistically driven approvals work, the following procedure
uses the AP:Detail-Signature form to view the approval status after a response by each
approver.
To observe the approval process in the AP:Detail-Signature form
1. Using a browser, log in to BMC Remedy AR System as an administrator, and open the AP:
Detail-Signature form in Search mode.
2. In the Approval Status field, select Pending, and click Search.
The approval request created by Frank Williams is pending for Jack Miller, Larry Goldstein,
and Violet Anderson.
3. Log in as Jack Miller, open Approval Central, and approve the request from Frank Williams.
Observing rule activity in the AP:Detail-Signature form


4. Repeat steps 1 and 2.

The sample statistical decision-making rules require the cumulative signature authority to be
greater than $500. Because Jack's signature authority is weighted at $100, the approval is
still pending for either Larry or Violet's signature.
5. Log in as Larry Goldstein, open Approval Central, and approve the request from Frank
Williams.
6. Repeat steps 1 and 2.
The request is no longer pending when you search the AP:Detail-Signature form. Because
the cumulative signature authority of Jack Miller and Larry Goldstein is $600 ($100 + $500),
the approval condition in the Issue Statistical Approval rule is met, and the request is
approved, even though Violet has not responded.
Violet's signature authority is weighted at $2000. Therefore, Violet could have approved
Frank's request without requiring either Larry or Jack's approval.
Example of a Statistical Override rule with default data

The approval server automatically populates the hidden Total fields in the join forms with the
number of signature records in Pending, Approved, Rejected, Hold, More Information, Cancelled,
Error, and Closed states. You can use these field values in Statistical Override rules. In this case,
no Signature Accumulator rule is necessary.
For example, the following Run If condition would check if 50 percent or more of the signatures
have been approved:

$Total Approved$ / $Total Signatures$ >= . 5
When the Run If condition has been met, the preempted decision is specified on the Set Fields
tab.
Defining Completion rules

A Completion rule determines when the approval routing process is complete. For example, a
Completion rule can compare the current approver's signature authority against the estimated total
on the approval request.
Completion rules are usually teamed with the Get Authority or Get Authority Regular rules. The
authority rules retrieve information about an individual's or role's authority from other forms and
make the information available to Completion rules.
To define a Completion rule
Select Completion from the Rule Type list.
Construct a rule condition. The Completion rule condition defines whether the
approval process is complete (no further routing of the request is necessary). If the
condition is met, the process is complete. If it is not met, the approval server returns
the request to the Get Next Approver stage of the approval process.
2. Click Save.
Example of a Completion rule
The following figure illustrates an example Completion rule from the Lunch Scheduler sample
application. In this example, the temporary field Temp Decimal 1 on the AP:Detail form contains
the current approver's signature limit, which was retrieved by a Get Authority rule. The rule
compares the Estimated Total field on the approval request to this signature limit. If the condition
passes, the approval process is considered complete.
You must define a Get Authority or a Get Authority Regular rule for the Completion rule to work
correctly in this example.
Example of a Completion rule

Defining Approval Process Done rules

Approval Process Done rules define the actions taken when the approval process is done. The
approval process is considered done when an approval request is approved and passes a
Completion rule, or if it is Rejected, Cancelled, or ends with an approval error.
Approval Process Done rules are often used to change the state of the approval request. For
example, you use one Approval Process Done rule to change the state of the approval request to
Approved and another Approval Process Done rule to change the state of the approval request to
Rejected.
When an approver marks an approval request as either Approved or Rejected, the approval server
sets this status in the AP:Signature record for that approver. When the conditions are met to
approve the request, as determined by the process definition or a Completion rule, the approval
server sets the status in the AP:Detail record for the request. To change the status in the approval
request form, you use an Approval Process Done rule. This also applies to approval requests that
are cancelled or that end in an error.
To define an Approval Process Done rule
Select Approval Process Done from the Rule Type list.
Select one or more rule conditions from among the radio buttons: Approved,
Rejected, Cancelled, or Error.
The rule executes when the AP:Detail record is put into the selected state.
2.

3. Select a value from the Set Field Type list. See Using the Set Fields tab on the Rule
Definition form (see page ).
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 (see page ).
Example of an Approval Process Done rule
Working with existing rules

This topic contains information about viewing, modifying, and deleting existing approval rules.
To filter the list by process type (see page 1705)

To filter the list by rule type (see page 1705)
To modify a rule (see page 1705)
To delete a rule (see page 1705)

You can use the table of rules on the Rule tab of AP:Administration to filter rules by process, or by
rule type.
To filter the list by process type
1. Open the AP:Administration form and click the Rule tab.

2. In the Show For Process field, select the name of the process whose rules you want to view,
for example, Issue Approval.
The list is refreshed with rules that belong to the selected process.
To filter the list by rule type

2. Clear any process name from the Show For Process field.
3. In the diagram below the table of rules, click the link for the rule type you want to view, for
example, Process Done.
The list is refreshed to show all existing rules of the selected type.
To modify a rule

2. Select the rule to be modified, and click View.
The AP:Rule Definition form opens in Modify mode, showing the current values for the rule.
3. Modify the rule as needed. For specific information about fields in the rule, see the
"Defining" topic for the rule type.
4. Click Save.
To delete a rule
Note
The delete operation is permanent and cannot be undone. Check for any rule
dependencies before deleting a rule. For example, Self Approval and Completion rules
might depend on a Get Authority, Get Authority Regular, or Get Authority Self rule. If the
Get Authority rule is deleted, the dependent rule will no longer function as designed.

2. Select the rule to be deleted from the list, and click Delete.
3. Click Yes when prompted to confirm the deletion.
The rule is deleted and no longer appears in the list of rules.

Using the Lunch Scheduler sample application

The Lunch Scheduler is a sample application deployed with BMC Remedy Approval Server
(approval server).
The following topics provide information about the purpose of the three processes in Lunch
Scheduler, and illustrates how to chain several processes together to form one approval process:
Lunch Scheduler application introduction (see page 1706)

Main Lunch Scheduler forms (see page 1708)
Sample process descriptions (see page 1708)
Chaining approval processes (see page 1710)
Working with sample users (see page 1712)
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 (see page ).
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 (see page 2867).
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 (see page 1783).
Main Lunch Scheduler forms

This section lists the main forms associated with the Lunch Scheduler application.
AP-Sample:Lunch Scheduler — This is the approval request form for the application.
AP-Sample:Lunch-Detail — This is the inner join between the AP-Sample:Lunch
Scheduler and AP:Detail forms. It is used for internal processing by the approval server and
for Global Override operations. The join criteria is Request ID to Request.
AP-Sample:Lunch-Detail-Signatu — This is the three-way inner join between the AP-
Sample:Lunch Scheduler and AP:Detail-Signature forms. This is the detail form that is
available to approvers when they choose to view a request in Approval Central. The join
criteria is Request ID to Request.
AP-Sample:Company — This is a supporting form that stores data about customer
accounts. This data supports menus, workflow, and queries about the customer companies
in the application.
AP-Sample:Restaurant — This is a supporting form that stores data about restaurants.
This data supports menus, workflow, and queries about the restaurants in the application.
AP-Sample:Signature Authority — This is a supporting form that stores data about
approvers. The approval server uses this data from this form to identify hierarchical
relationships in the organization. This data supplies information about the account teams
and is used to identify next approvers in the Parent-Child and Level processes. The
application's rules and processes use information from this form about approvers' signature
authority to determine routing and whether the process is done.
Sample process descriptions

In this topic:
Management cost authorization (see page 1709)

Major account level approval (see page 1709)

Special overdue approval (see page 1710)
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 (see page ).
Management cost authorization

This is a Parent-Child process that runs first and acts on every request. It uses Auto Approval and
Self Approval rules to determine if the requester has authority to approve his or her own request. If
not, the approval process routes the request to the manager by using the AP-Sample:Signature
Authority form. The approval server routes the request to subsequent managers until a manager
with sufficient authority signs the request. If no one with sufficient authority can be found for an
individual, or if an individual has no manager, the process terminates with an error.
The filter AP-Sample:Start Cost Approval starts the Management Cost Authorization process. This
filter uses the following application command:
Application-Command Approval New-Details -t "Management Cost

Authorization"
In this command, the -t option identifies the name of the process to run. See BMC Remedy
Major account level approval

This is a Level process that runs if the request is for lunch with a major or enterprise account. The
process uses a Completion rule to stop lunch requests for major accounts from advancing beyond
the major account level. Only enterprise accounts need to go to both the major account and
enterprise account levels. The Account Type field on the request form identifies the account as a
major or enterprise account.
The filter AP-Sample:Start Level Approval starts the Major Account Level Approval process. The
Run If criteria in the filter must be met for this filter to run. The filter uses the following command:
Application-Command Approval New-Details -s "$SCHEMA$" -e

"$Request ID$" -t "Major Account Level Approval"
In this command, the -s option identifies the name of the approval request form, the -e option
identifies the request ID for the current request, and the -t option identifies the name of the process
to run. See BMC Remedy Approval Server application commands (see page 2903).

Special overdue approval

This is a Rule-Based process that runs only if the company currently has an overdue account. This
process includes an example of using Prep Get Next Approver rules, which retrieve and set data
for Get Next Approver processing. The Account Overdue check box on the AP-Sample:Company
form identifies whether the account is overdue.
The filter AP-Sample:Start Overdue Approv starts the Special Overdue Approval process. The Run
If criteria of the filter must be met for this filter to run. The filter uses the following command:
Application-Command Approval New-Details -t "Special Overdue Approval"
In this command, the -t option identifies the name of the process to run. See BMC Remedy
Chaining approval processes

In this topic:
Using filters and a process status field (see page 1710)

Restarting an approval process (see page 1712)
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.
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

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 (see page 1713)

User forms (see page 1763)
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 (see page 1714)

AP-Administration form (see page 1715)
AP-Admin-DeleteVerify form (see page 1716)
AP-Admin-Rename form (see page 1717)
AP-Admin-ServerSettings form (see page 1718)
AP-Customize-SourceID form (see page 1722)
AP-Detail form (see page 1724)
AP-Detail-Signature form (see page 1725)
AP-DynamicLabels form (see page 1727)
AP-Form form (see page 1729)
AP-Notification form (see page 1734)
AP-Preview Data form (see page 1738)
AP-PreviewInfo form (see page 1739)

AP-PreviewSignatures form (see page 1740)

AP-Process Administrator form (see page 1741)
AP-Process Definition form (see page 1743)
AP-Question-Comment-Info form (see page 1753)
AP-Reserved Word form (see page 1754)
AP-Role form (see page 1754)
AP-Rule Definition form (see page 1756)
AP-Signature form (see page 1760)
AP-AdhocDetails form
This form stores the information entered through the AP:AdhocDialog form. See AP-AdhocDialog
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 (see page
3024).
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 (see page 596).
AP:Administration form — Process tab

Fields on the AP:Administration form
Field Description
Show for process Use the menu to limit the display list to items associated with the selected process. This
field is not active for the Role and Form categories.
Process, rule, notification, role, form, Click a tab to display a list of items of that type. This also selects which category of items
administrator, alternate is used when you click the buttons on this form.
View Click this button to open the item selected.
Search Click this button to open a search form for items of the category determined by the
current tab.
Create Click this button to create a new item of the category determined by the current tab.
Delete Click this button to delete the currently selected item.
Refresh Click this button to reload the displayed list.
Server settings Click this link in the navigation pane to open the Server Settings form. See AP-Admin-
ServerSettings form (see page 1718).
Rename Click this link in the navigation pane to open the AP:Admin-Rename form. See AP-
Admin-Rename form (see page 1717).
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 Select Process to rename a process, or Form to rename a form.
be renamed
Select the form to be Select the process name from the menu. When BMC Remedy AR System supplies the GUID,
renamed /Select GUID of the select the supplied GUID.
process to be renamed
Enter new process name / Type the replacement name for the process or form. The name of a process can be as long as
Enter new form name 80 bytes. This 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.
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
Note : By default, the arapprov.log file is displayed in the AR server in the AP:Admin-ServerSettings form. The
log file is located in the AR server machine at <AR System Installation Directory>\Arserver\Db.
Other Settings
Definition Type a number of seconds to define how often the approval server checks the definitions for changes. A larger
Check number increases BMC Remedy AR System performance by checking less often. A smaller number of seconds is
Interval useful while creating and testing a process. A zero (0) in this field causes the system to check for definition changes
with each operation.
Note: When testing custom applications, after creating a process, you should wait until the Definition Check Interval
period before creating requests. Otherwise, the processing of requests fails, and the following error is written to the
logs:
No join between applicationFormName and the approval detail form.
Private Type the RPC socket number of a private queue to use when accessing the AR System server. Leave this field
AR empty if you do not use a private queue.
Server
RPC
Socket
Plugin Type the RPC socket number of a private queue used for loopback calls. Leave this field empty if your server does
Loopback not use a dedicated queue for loopback calls.
RPC
Socket
Due- Type the duration after which approval requests that are due for action should be highlighted on Approval Central.
Soon Use the adjacent drop-down list to specify whether this duration should be measured in hours or days. This interval is
Interval 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 (see page ). For example,
if the process states that the automatic action interval for a request is five days, and the Due-Soon Interval is four
days, the request appears as a Due-Soon approval for the relevant approver one day before the automatic action is
due.
Recent Type the duration within which a user can see in the recent history an approval request that was submitted or acted
History upon. Select the unit of measurement (Hours or Days) using the adjacent drop-down list. This affects My Recent
Interval Approvals on Approval Central. See Approval Central (see page ).

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 (see page 4333).
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 Reject by /at Later Level

Approve
Alternate Reject Cancel at Later Level
Override Reject by Another Approver

Approve
Override Reject Hold
Global Approve More Info
Global Reject Change After Approval /

Approved
Reassign Before Reassign
When any of these event types occur during an approval process, the approval server acts
according to the following choices:
Disabled — No notifications are sent.

Enabled — Notifications are sent to all the approvers.
Enabled Including Alternate (default setting) — Notifications are sent to all the approvers
and active alternates.
To use notifications, you must define the specific notifications for each process in the AP:
For information about the notification tab, see Setting notifications for approval events (see page
3009).

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
(repeat) during an approval process.
Enabled Including Alternate (default setting) means the approval server enables escalations to the approver
Still
list as well all active alternates when this event type occurs during an approval process.
Pending
These settings enable escalations for each event type. To use escalations, you must define the specific
Still
escalations for each process in the AP:Process Definition form.
Pending
(repeat)
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 (see page 3010
).
AP-Customize-SourceID form
This form appears when you click the Customize link on the Basic tab on the AP:Form. This form
enables you to specify the application form that opens when users click the Request ID link on
Approval Central.
The following table lists the fields available on the AP:Customize-SourceID form and their
descriptions.
Fields on the AP:Customize-SourceID form
Fields Descriptions
Display Displays the following window types. For information about each window type, see the Open Window action. Select
Mode the mode in which you want to open the custom form.
Modify
Display
Modify Directly
Display Directly
Dialog
Search
Submit
Form Displays the list of all available forms on the server, except the Display-Only forms.
Name
Note
If you selected Dialog for the Display Mode field, the Form Name list also includes the Display-Only form
names.
Select the form you want to open when you click the Request ID link on Approval Central.
View 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
Mappings application request form.
Note
This option appears if you selected Dialog, Submit or Search in the Display Mode field.
Select an application request form field from the menu list that you want to map with the custom form field. You can
map up to 10 fields from the application request form to the custom form. The reserved IDs (14301 to 14310) are
assigned to these fields on the custom form. When you open the custom form through the Request ID link, these
mappings populate the custom form fields (14301 to 14310) with the corresponding values on the request form fields
that you selected or mapped for the current request.
Note
If you do not define the mapping between the custom form fields and the application request form, a blank
form opens when you click the Request ID link on Approval Central.

AP-Detail form
This form holds all data about an approval request. You can use this form to determine the status
of a request, and to see a history of activity on the request for any approval process. In addition to
the fields described in this section, the AP:Detail form also includes hidden Currency, Date, and
Time fields to store temporary results during workflow. For example, Currency Field 1 and
Currency Field 2 are temporary fields of the currency type.
AP:Detail form
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 This field contains an audit trail of date, time, and approver for actions taken on this request. This information is
Audit Trail part of the permanent record for this request.
Global Approves the request, overriding the regular approval process. You must have process administrator override
Approve authority to perform this action. However, BMC recommends using Approval Central for overrides.
Global Reject

Field Description
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 The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports
Group the multi-tenancy feature.
Permissions
Process The BMC Remedy AR System populates this field with the GUID for the process associated with the request.
Instance ID
Signing Tracks the method (Approval Console or Email Engine) used for approving or rejecting a request.
Method
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
Approvers the Next Approver field.
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.

Field Description
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 Type the AR System user name of an approver to whom you want to reassign this request.
To
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
Audit Trail part of the permanent record for this request.
Assignee The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the
Group multi-tenancy feature.
Permission
For The BMC Remedy AR System populates this field with the name of the approval request form for the request.
Application
For The BMC Remedy AR System populates this field with the AR System ID for the request.
Request
For The BMC Remedy AR System populates this field with the name of the approval process of this request.
Process
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
Signature appears only after an 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
Signature any.
More This field contains More Information requests sent by the approver for this request and signature line, and the
Information responses to those 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
information request.
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
14508 labels appear, see AP-Form form (see page 1729).
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
14711 click Save. For information about where these labels appear, see AP-Form form. (see page 1729)
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.

Field Description
Approval Enter the name of a form used for reporting, if any.

Reporting
Assignee Group The BMC Remedy AR System populates this field with the Assignee Group for the request. This field
Permission supports the multi-tenancy feature.
Search In Search mode, click this button to perform your search.
Save In Submit mode, click this button to save your changes.
Close Click this button to close the window.
Advanced tab
The Advanced tab enables Process administrators to define field mappings for a request form at
the application level. These mappings are not mandatory. Not all field types are supported for
mapping.
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
Request ID Change Management uses its own IDs to represent a particular record, apart from the one generated by BMC
Remedy AR System. You can map this field to that field from the BMC Change Management application. The
value from the mapped field is displayed on Approval Central as the Request ID link. If the value is NULL, the
request ID is displayed by default. See Approval Central (see page 1764).
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
{14507} certain fields on the 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
{14508} of the Lunch Scheduler sample application, these values appear against the following labels:
Field 4
{14509} P-C GL Account
Field 5 P-C Cost Center
{14510} P-C Total Cost
Field 6 P-C Phase
{14511}
In your application, you can specify the labels that should appear for these fields on AP:Show-Detail.

Field 7 The value from the mapped field can be used in accordance with the user requirement. Currently, the value of this
{14512} 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 Click to define labels for the fields 14508, 14509, 14510, and 14511, for various applications, processes, and
Labels locales. The AP:DynamicLabels form appears. See AP-DynamicLabels form (see page 1727).
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
{14711} of the request on 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
Field 3 fields, but not defined any labels, 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,
Labels for various applications, processes, and locales. The AP:DynamicLabels form appears. See AP-DynamicLabels
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 (see page 1777).

AP-Notification form
Process administrators use this form to create and modify notifications sent by approval processes.
This form opens from when you click View or Create from the Notification tab of the AP:
Basic tab
AP:Notification form — Basic tab
Fields on the AP:Notification form — Basic tab

Field Description
Notification Type a name for the notification.

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

Field Description
Inactive — The notification will not be sent.
Process Instance The BMC Remedy AR System populates this field with the GUID of the selected process.
ID
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 supports the 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 (see
page 3016).
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 (see page 1743).
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 Select "Yes" to use the email based approval template. The appropriate template name will be automatically
based Approval displayed in the Content field. Default value is "No".
template
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

Field Description
Note: If you select "Yes" for the Use Email based Approval template field, the template name will be
automatically displayed for this field.
Footer Enter the names of templates to use for the footer of the email notification. You can enter the name of the
For information about the Administrative Information tab, see Administrative Information tab (see
page ).
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 (see page 3023).
The field values correspond to the input parameter values of the Generate-Multi-Process-Preview
command. See BMC Remedy Approval Server application commands (see page 2903).
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

Field Description
Preview Indicates whether a single process or multi-process preview is generated.

Type
Process List The list of processes separated by semicolons (; ).
Phase- The semicolon-separated list of processes, each prefixed with some related information and separated by a colon
Process List (: ). Some processes might not have any related information prefixed.
AP-PreviewInfo form
The approval server uses this form to store preview data when the process is configured to
generate previews. Process administrators can use this form to preview all the approvers assigned
to work on an approval request.
You must enter data into all the visible fields to search the AP:PreviewInfo form.
See Configuring approval server to work with flowcharts (see page 599).
AP:PreviewInfo form
Fields on the AP:PreviewInfo form
Field Description
Request The request ID that you want previewed.

/Ticket
Number
Single Select the appropriate value to indicate whether you want to generate a single process or multi-process preview.
/Multi
Process
Retrieval Users have an option of specifying a value as a qualification for the query being made.
Type
Full — Returns list of all completed signatures (from the AP:Signature form), and all previews from the
preview form.
Remaining — Returns list of only the preview signatures (those that are not yet opened and entered in the
AP:Signature form).

Field Description
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 The current status of the request.

Status
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 (see
page ).
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.

Field Description
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 (see
page ).
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 (see page 1658).
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 (see page 1632).
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:

Field Description
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
Owner Field menu. The fields in this menu are populated from the approval request form. See Request Owner field (see page
1748).
First Enter a valid AR System user name or select the field that identifies the first approver for this process from the
Approver menu. The fields in this menu are populated from the approval request form. This field is required for Ad Hoc
Field process type, optional if you allow ad hoc 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
Reassign? approver.
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
Form custom form name by using the adjacent text field. This information is pushed to the Full Name field on the AP:
Signature form. For more information, see Full Name (see page 1760) and Full name form (see page 1748).
Exclude This menu lists all the fields on the application form. Select a field that contains user names. The users from the
User Field selected field are excluded from the list of approvers (their signatures are not created) for a request of this
process type. If the selected field contains a role:
Users belonging to that role are excluded.

If the role is part of an approval chain and contains only one user, the other approvers can act on the
request and the process can complete successfully regardless of the One Must Sign or All Must Sign
setting. If an excluded user is an approver in the middle of an approval chain, the approver before the
excluded user can act on the request, and the request remains open. However, when the excluded user is
encountered, the request state is changed to Error on the application and detail form, and no further action
can be taken. The exclusion takes place only after the Get Next Approver rule is executed. Because these
users are excluded from the list of approvers, they do not appear on the Approver tab of the AP:Show-

Field Description
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
Success complete:
No More Approvers — (Default) The process is complete when all signature lines are complete. If you
select this option and if the signature line for a request is cancelled and no other signature exists, the
request is marked Approved, not Cancelled.
Completion Rule — Use a Completion rule to determine the successful completion of the approval
process. If you select this option, you must create a Completion rule and associate it with this process or
the process is never considered complete.
If Multiple This field applies only if you are defining an Ad Hoc process or are going to allow ad hoc overrides. The value you
Approvers select determines how many signature line records the approval server creates when building an approver list.
Specify using the available options how to manage signature entries when a request is assigned to multiple
approvers:
One Must Sign — Create only one signature line for a list of potential approvers. The signature line is
complete when one of the approvers acts on the request. The first approver to act on the request
determines the response; the request is withdrawn from the other approvers.
Note: The field for approver names on a signature-line record is limited to 255 characters on certain
databases. Using roles might help you to work around this limitation, because roles are internally expanded
to individual approver names during further processing.
This option overrides 4the If Multiple Approver setting on any roles selected as an approver.
All Must Sign — Create separate signature lines for each approver. All approvers must act on their own
signature line for the request to proceed.
If an approver list includes roles, the If Multiple Approver setting for the specific role determines whether the role
is expanded into individual signature lines for each member of the role or a single signature line is created for the
entire role. See Defining roles (see page ).
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
(see page 1734).
Allow Ad This field applies to Parent-Child, Level, and Rule-Based process types. Specify using the available option
Hoc Next whether users can add approvers to the approver list for a request:
Approver?

Field Description
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
Assignment who submitted the approval request (for example, when an assistant enters an approval request on behalf of
someone else). Select from the available options:
Use Get Next Approver Rules — (Default) Use a Get Next Approver rule to determine the first approver.
Assign to Owner if Approver — Use the requester as the first approver if the requester is defined as a valid
approver for the approval server. If you select this option, you must define a Validate Approver rule to verify
whether the owner is a valid approver.
Always Assign to Owner — Use the requestor as the first approver in all cases.
Validate This field tells the approval server whether to verify the value in your next approver field with a Validate Approver
Approvers rule when creating a 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.
password Select from the Available options:
Yes — Mandate the use of a password when saving changes to an approval request.
No — (Default) Allow saving changes to request without validating the password.
Assignee The BMC Remedy AR System populates this field with the Assignee Group for the request; the Public group is
Group selected by default. The approval server uses this field to support multi-tenancy for use by application service
Permissions providers. If you use this field for multi-tenancy support, create workflow to populate this field with the correct
assignee group name. You do not need to change this setting when creating the rule. The ID of this field is 112,
and it appears on all approval server forms. The field 112 value from records created in the AP:Detail form is
used automatically in all the other approval server forms (for example, AP:Signature, AP:More Information, and
so on). See Error 333 and Assignee Group Permission (see page 4678).
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
Form when an approver clicks the Adhoc button on the AP:Show-Detail form. Approvers should be able to provide data
about ad hoc approvers in this form, and the form should have the necessary workflow to store this data in the AP:
AdhocDetails form. If you select a custom form, make sure that application developers have added the necessary
fields and workflow to it.
This field determines the course of action in case the approval server fails to retrieve the first approver for a
request.

Field Description
Retrieving Yes — (Default) Set the state of the request to Error and add the error details to the audit trail.
first No — Set the state of the request to Pending. Later, if Add-Sig is started for that request, the same AP:
approver Detail record is used.
failed,
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 (see page 1760).
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 (see page 1638).
Process Due Enter a number in the Interval field and the select the Unit of measurement. This specifies the total duration in
which the process is due.
Signature Enter a number in the Interval field and the select the Unit of measurement. This specifies the total duration in
Due which each signature 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
Period delta to be deducted 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
Preview information about the future approvers, to calculate the total number of signatures required to complete the
process. The Signature Due interval is then computed as the Process Due interval divided by the total number of
signatures required. Select No to avoid the use of the Preview feature. In this case, only the value specified in
Signature Due is considered.
Note: This field is used only in the case of Parent-Child and Level processes. The value of this field is not
considered when calculating the Signature Due interval for ad hoc requests.
Specify menu name to list users for the following operations
More Select the menu from which to derive user names for the corresponding operations. The selected menu
Information determines the list of users that appears when a user creates a More Information request (by adding a question
Reassign or comment), or chooses to reassign a request, or to assign a request to an ad hoc approver. If you do not
Ad-hoc specify a menu for any of these operations, users do not have the option of choosing names from a user list; they
can continue with the operation by entering login names manually.

Field Description
Rejection Justification
Require Select Yes to make it mandatory for an approver to provide a justification when rejecting a request. In addition to
Justification storing the justification in various approval server fields, it is pushed to the application form's field specified in the
on Rejection Justification Field menu. Select No to indicate that rejection justification is optional; an approver is not prompted
to justify rejecting a request. However, if provided, the justification is processed further.
Justification Select the field in which to store the rejection justification. This menu lists Character fields from the application
Field form.
Note: Currently, this menu also displays Attachment fields along with Character fields, because of an AR System
server issue.
From the list of available fields, select a Character field whose length is unrestricted (0 ). Otherwise, if the
approver enters a justification of more than 255 characters:* A warning is added to the approval log.
The justification is not made available on the application form.
If you do not select a field from this menu, the approver's input is stored in the Justification field (ID 14518) on AP:
Signature and as a comment of the Justification type on AP:Question-Comment-Info. See AP-Rejection
Justification form (see page 1782).
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 Type a numeric value for the amount of time to pass before this action is taken. For example, type a 2 for two hours
Interval 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
State defined in the two preceding fields. Leave this field and the preceding two empty if you do not want the status of a
request changed automatically.
Note: This reflects on AP:Show-Detail > Action Date field and Approval Central > Action Date column. See AP-
Show-Detail form and Approval Central.
Notifications (Notification: Still Outstanding and Notification: Still in State) are used to determine the escalation or
notification mechanism for signatures on a request.
Notification: Still Outstanding 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
Interval hours or two days. The 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 State Set the separate escalation and repeat intervals to occur when a form is saved with the status of Pending, Error,
Hold, or More Information.
First Type a numeric value for the amount of time to pass before this notification first occurs. For example, type a 2 for
Interval two hours or two days. 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.

Field Description
Repeat Type a numeric value for the amount of time to pass before this notification recurs. For example, type a 2 for two
Interval hours or two days. The 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

Field Description
First Type a numeric value for the amount of time to pass before this action first occurs. For example, type a 2 for two
interval 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
interval or two days. The unit is determined in the next field.
Administrative info tab

For more information about the Administrative Information tab, see Administrative Information tab
(see page ).
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 Source field

type
Question Stores text from the Question field on AP:Show-Detail or AP:More Information.
Comment Stores text from the Summary field on AP:Show-Detail or the Comment field (if added) on the application form. If
you add an activity log entry of the Justification type on AP:Show-Detail, text from the Summary field is also stored
here. Attachments associated with comments are stored in the attachments table adjacent to this field.
Justification Stores text from the Justification For Action field on AP:Show-Detail or Approval Central. If the Justification For
Action field and its appropriate workflow is added to the application form or the three-way join form, the
corresponding text is stored here.
This form also stores the text from the following sources:
Form Field
AP:More Response
Information
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
(see page ).
AP:Role form — Role Information tab

(see page ).
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 (see page 1669).
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 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.

Process
Instance ID
Rule Type Use the drop-down list to select the rule type. See Defining approval rules (see page 1668)
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.
Assignee The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the
Group multi-tenancy feature. See Error 333 and Assignee Group Permission (see page 4678).
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 (see page 1669). 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 (see page 1669). 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:
Type Value, Query, SQL, Process, and Other.
From Form For a query, select the name of the form that contains the data to retrieve.
On Server Use the drop-down list to select the server that contains the form.

Current — Select this option if the form resides on the same server as the approval server.
Alternate — Select this option if the form resides on another server.
Server Type the name of the server that holds the form. This field is available only when the On Server field contains the
value Alternate.
Separator Type the letters, numbers, or symbols to use when separating multiple entries set in the same field. This field is
string disabled with some 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
builder are available for use only when you select a Set Fields type other than Value. For example, choosing SQL causes
buttons Select, From, Where, and the comma 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
Command / criteria by using the EXTERNAL keyword. When using the EXTERNAL keyword, make sure you see fields using
Qualification single quotes instead of dollar signs, for 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.
(see page ).
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 The BMC Remedy AR System populates this field with the questions and answers to More Information
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 The BMC Remedy AR System populates this field with the user name of an alternate approver, if the
Signature alternate acts on the request.
Approver The BMC Remedy AR System populates this field with the user name of the approver when the approver acts
Signature on the request.
Signature The BMC Remedy AR System populates this field with the method by which this request was approved.
Method
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.

Field Description
Permissions supports the 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 (see page
).
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 (see page 1743).
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 (see page 1764)

AP-AdhocDialog form (see page 1775)
AP-Alternate form (see page 1777)
AP-Dtl-Sig-MoreInfoDialog form (see page 1780)

AP-More Information form (see page 1781)

AP-Password form (see page 1782)
AP-Reassign form (see page 1782)
AP-Rejection Justification form (see page 1782)
AP-Show-Detail form (see page 1783)
AP-ShowDetail-DeleteVerify form (see page 1791)
AR System Business Time forms (see page 1791)
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 (see page 285).
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 (see page 1024).
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 (see page 1770).
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
Approvals displayed under the Pending Approval link:
Needs Attention
Past Due
Due Soon
For more information, see Pending Approvals table (see page 1766).
Needs Click to view the requests for which a question or answer is directed at you. Such requests are in the More
Attention Information state. The Need Attention Approvals panel displays a table with the columns: From, To, Action Date,
Description, Application, Request, and Status.
Past Due Click to view the requests whose Action Date has passed. The Past Due Approvals table displays requests having
the Pending, Hold, or More Information status. For more information about the Action Date, see step 5 (see page 1661
) and step 6 (see page 1662) of the To enter signature escalations (see page 1661) section.
Due Click to view the requests whose Action Date is approaching. The Due Soon Approvals table displays requests
Soon 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 (see page 1661) of the To enter signature escalations (see page 1661) section.
My Click to view the requests that you approved or rejected, and requests that have the Error status. This is a pre-
Approval defined search, the results of which appear on the right pane in the My Approvals History table. Requests
History displayed in this table have the Approved, Rejected, or Error status. A Process Administrator configures the number
of history items to display. See AP-Admin-ServerSettings form (see page 1718). 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
by Others sequence. This is a pre-defined search, the results of which appear on the right pane in the Approvals Rejected by
Others panel.
Approval requests that need attention

When you click the Needs Attention link in the Summary section of the left pane, a table of
questions and answers posted to you appears in the right pane.
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 Click this link to open the AP:Alternate form in New mode. For more information, see AP-Alternate form
Approvers (see page 1777).
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 (see page 1772).
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 (see page 1750) and step 5 (see page 1661) of the To enter signature escalations (see page 1661)
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 (see page ).
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 (see page 1028).
Hold icon Click to put the selected request on hold.
In case of approval generated by a Process Designer process, the Hold option is not supported for SRM and
Change requests.
Reassign Click to reassign the selected request to another person. If Can Reassign is set to Yes for the corresponding
icon process, the AP:Reassign dialog box prompts you to enter the name of an approver; otherwise an error is
displayed. For more information, see Reassigning approval requests (see page 1046).
In case of approval generated by a Process Designer process, the Reassign option is not supported for Service
Request Management (SRM) and Change requests.
Note

The AP:Reassign dialog box appears only once, which means that all the selected requests are assigned
to the same person. Validation for the user name entered in the dialog box is not provided out-of-the-box.
Approval Click to open the AP:Show-Detail form, which displays the details of the highlighted approval request and enables
Details icon you to take further action.
Note
When you click the Approval Details icon on the Approval Central form, if the AP:Show-Detail form does
not load the sequence diagram, the following error message appears: Error during loading
document
To fix the issue, perform the following steps:
1. Open the Visualizer Module Registration form.

2. Click Search.
3. Select the BMC Remedy Approval Server record that has an attachment of the Approval_0.jar
file.
4. Delete the attachment and add the Approval_0.jar file again.
5. Restart BMC Remedy Mid Tier
6. Stop the running Apache Tomcat service.
7. From the BMC Remedy Mid Tier Install folder, delete the contents in the PluginCache folder.
8. Start the Tomcat service and open the Approval Central form.
9. Select a request and click the Approval Details icon.
You can see the sequence diagram without errors.
For more information, see Working with request details. (see page 1029)
View Click to display all the questions and responses, if any, for the selected request. If there is no question for the
Questions selected request, the 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
For Action is added to the 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. (see page 1028)
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 (see page 1750) and step 5 (see page 1661) of the To enter
Date signature escalations (see page 1661) section.
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- Type the Request ID to search for approval requests.

ID
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 (see page 1772).
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 (see page 1750) and step 5 (see page 1661) of the To enter signature escalations (see page 1661)
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 (see page ).
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. (see page 1028)
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
icon process, the AP:Reassign dialog box prompts you to enter the name of an approver; otherwise an error is
displayed. For more information, see Reassigning approval requests (see page 1046).
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
Details icon you to take further action. For more information, see Working with request details (see page 1029).
View Click to display all the questions and responses, if any, for the selected request. If there are no questions for the
Questions selected request, the following pop-up message is displayed:
and
Responses No Questions Present
icon
Justification Enter some meaningful text in this field to be recorded as a justification for your action, and click Reject. An entry
For Action is added to the 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. (see page 1028)
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
Selected requests to the respective next approvers. If no further approvers are required, the request statuses change
to Approved, and the approval process is done.
Reject Click to reject the selected requests. If rejection justification is mandatory, but the Justification For Action
Selected field is empty, a dialog box prompts you to enter a reason for rejecting the request. The same comment is
applied to all the selected requests. See Rejection justification for approval requests. (see page 1028)
Hold Click to put the selected requests on hold. The request statuses change to Hold until any further action is
Selected performed on them.
Request Details
The Request Details section displays all the data related to an approval request. This data is
fetched from the AP:Show-Detail form. For more information, see AP:Show-Detail form (see page
1783).

For information about the approval request details, see AP:Detail form (see page ).
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
ID relevant application form.
Note
If you upgrade from an earlier version of the BMC Remedy Approval Server to 7.5.00 or later, this link
displays the correct application ID for newly created requests. The application ID might not be accurate for
requests that were created before upgrading. To specify the value for this link, the process administrator
must map the Application Request ID field on the Advanced tab of AP:Form to the appropriate field on the
application form. See AP:Form form (see page ).
Activity Displays the activity log (Questions, Comments, and other information) associated with the Request ID. Click View
Log Activity Summary to view all the activities related to the current request in a report format.
When you click any of the Approve, Reject, or Hold, or Reassign icons, a dialog box prompts you
to enter your password. The statuses of the selected requests are changed only if you provide a
valid password, otherwise an error message is displayed.
More Information
The More Information section enables you to add questions or comments to the current request in
a table.
More Information section on Approval Central
To modify or delete questions or comments associated with the current request, you must go to the
Activity Log tab on the AP:Show-Detail form.

For more information, see Activity Log tab (see page 1788).
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
To question. This field is enabled only if you select Question from the Type drop-down list. Using the Question To field,
an approver can ask questions to the requestor or any other person who belongs to the same group as the approver.
Note
The approval server does not have any 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
/ Notes appears here. It is labeled as Notes when you choose to add a comment; enter the detailed comment here.
Save Click to save a new comment or question.
AP-AdhocDialog form
This form appears when you click the Adhoc button on the AP:Show-Detail form for a request. The
appearance of this dialog box is dependent on the value of the Ad Hoc Settings field on the AP:
Process Definition form; it appears only if the Default option is selected. However, if the process
administrator selects the User Defined option, the custom dialog box for the corresponding form is
displayed.
The AP:AdhocDialog form shows the list of existing ad hoc approvers, if any, and enables you to
add to or remove from this list. If the table contains multiple rows, the first row is selected by
default.
AP:AdhocDialog form

Fields on the AP:AdhocDialog form

Field Description
Name Select a name from the user list or enter the name of a new ad hoc approver. You can also specify multiple ad hoc
approvers by typing their names separated by semicolons. If you select a row in the following table, the
corresponding approver name appears in this field, but you can modify and save it.
Sequence Enter or modify the sequence at which to add the ad hoc approver. The default is 1.

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.
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 BMC Remedy AR System automatically enters the GUID of the process selected in the Process field.
ID

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 Type any additional information to be recorded with the alternate assignment. This information becomes part of
history the permanent record for this alternate.
Last BMC Remedy AR System populates this field with the name of the person who last modified this alternate.
Modified By
BMC Remedy AR System populates this field with the date of the last modification to this alternate.

Last
Modified
Date
AP-Dtl-Sig-MoreInfoDialog form
This form appears when you click More Information on the AP:Detail-Signature form, or Manage
More Information on the three-way join forms in the sample applications. When opened, it is
populated with a list of More Information requests related to the current approval request.
AP:Dtl-Sig-MoreInfoDialog form
Fields on the AP:Dtl-Sig-MoreInfoDialog form
Field Description
Existing More 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 (see page 1743).
From AR System user name of the sender of the More Information request. This field is read-only after the record is
saved.
More Info Status 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.
The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the
multi-tenancy feature.

Field Description
Assignee
Group
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 (see page 1724).
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 (see page 285).

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
(see page 1743) and Creating signature escalations (see page 1660).
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
Log tab delete questions and comments.
Approve Click to approve the current request.
Reject Click to reject the current request.
Reassign Click to reassign the current request to another person. If Can Reassign is set to Yes for the corresponding process,
a dialog box prompts you to enter the name of an approver; otherwise an error is displayed.
Hold Click to put the current request on hold.
Adhoc Click to add ad hoc approvers to the approval chain or remove existing ad hoc approvers for the selected requests.
The table or flowchart in the Approver tab is updated accordingly. The Adhoc button is disabled in the following
conditions:
Ad Hoc Settings are not defined for the associated process.

The request is in the Process Done stage.
If the Default option is selected for the Ad Hoc Settings of a process, the AP:AdhocDialog appears for the
corresponding request. See AP-AdhocDialog form (see page 1775).
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
Type: is generated after the process begins (when the detail and signature records for the current request have been
Current created).
Process
Only
Preview Click to see a flowchart or tabular view of the path the current request might traverse when it pertains to multiple
Type: processes. This view appears only when the Generate-Multi-Process-Preview application command is executed,
Multiple whose input values determine the what appears in the view. See Using the multi-process preview (see page 3023).
Processes
View As: Click to see a flowchart view of the current approval request. See Sequence diagram (see page 1786).
Sequence
Diagram
View As: Click to see a tabular view of the current approval request. See Table (see page 1787).
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.
Justification Enter some meaningful text in this field to be recorded as a justification for your action, and click Reject. An entry is
For Action added to the 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 (see page 1028). 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
Details request.
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
To question. This field is enabled only if you select Question from the Type drop-down list. Using the Question To
field, an approver can ask questions to the requestor or any other person who belongs to the same group as the
approver.
Note
The approval server does not have any means to know where a particular user's details are stored. (The
consuming applications are responsible to validate the login name.) The source of a user could be any
form other than the User form that BMC Remedy AR System provides, for example, the user information
could be retrieved from an LDAP server.
Question / This field is labeled as Question when you choose to add a question to the approval request; enter the question
Summary here. It is labeled as 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
Notes response appears here. It is labeled as Notes when you choose to add a comment. Enter the detailed comment
here.
Attachment Use this field to add an attachment along with your comment. Only one attachment is allowed per comment. If you
view a comment that has an attachment associated with it this table field displays the file name, size, and label for
the same. Note that attachments cannot be associated with questions. This field is disabled when you select
Questions from the Type drop-down list.
Submitter Displays the name of the submitter.
Submit 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 (see page 1401).
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 (see page 3005))
Approval Change Schema - chgschema (See Approval Change Schema utility (see page
1656))
Approval Upgrade - upgrade (See Overview of the Approval upgrade utility in BMC
Remedy ITSM Deployment documentation)
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
3. Update Password Objects on Three-way Join Form
Arguments:
b. If you type chgschema, and press enter, the interface displays the parameters for
the utility and prompts the user to enter the required arguments as follows:
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 prompts the user to enter the required arguments as follows:
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.
Managing the BMC Remedy Single Sign-On

administrator console
BMC Remedy Single Sign-On provides the features listed in the following table:
Feature Details
Managing Server Configuration (see page 676) Add a cookie domain, set session details, enable logs, and enter SAML
information.
Manage realms in BMC Remedy Single Sign-On (see Add a realm, and add authentication to the realm.
page 1793)
Manage sessions View the following details of a session:
User ID
Realm
Time Remaining
Maximum Session Time
Managing realms in BMC Remedy Single Sign-

On
BMC Remedy Single Sign-On allows you to edit existing realm details and also add a new realm.
To edit realm details:

2. Click Realm.
3.
3. Click the pencil icon listed against a realm to edit it.
To add a new realm:

1. In the Realm window, click Add Realm.
2. In the General tab, enter the following details.

Field Parameter Description
Realm ID Enter the realm ID
Realm Enter the Realm Domains (as list of the values, separated by commas).
Domain(s)
Final Logout Enter the final logout URL.

URL This is the URL to which the user will be redirected to after user is logged out from BMC
Remedy Single Sign-On.
3. In the Authentication tab, select the SAML as the Authentication type.
4. Click Import against the Identity Provider to import the details or enter the following details.

4.
IdP Entity ID Enter identity provider entity ID.
Login URL Enter identify provider login URL.
Sign Request Specify whether SAML request will be signed.
Sign Response Specify whether SAML response will be signed.
Compress Request Specify whether SAML request will be compressed.
Transformation NONE NONE: No transformation will be effected.

TO_UPPER_CASE TO_UPPER_CASE: User id will be transformed to all upper case.
TO_LOWER_CASE TO_LOWER_CASE: User id will be transformed to all lower case.
REMOVE BMC REMOVE_BMC_DOMAIN: BMC specific transformation; email domain will be
DOMAIN removed from user id if it relates to BMC.
REMOVE EMAIL REMOVE_EMAIL_DOMAIN: email domain will be removed from user id.
DOMAIN
NameID Defines the name identifier formats supported by the service provider. Name
format identifiers are a way for providers to communicate with each other regarding a
user.
The Name ID format list is an ordered list, the first Name ID has the highest
priority in determining the Name ID format to use. If the user does not specify a
Name ID to use when initiating single sign-on, the first one in this list is chosen
and supported by the remote Identity Provider.
A persistent identifier is saved to a particular user's data store entry as the
value of two attributes. A transient identifier is temporary and no data will be
written to the user's persistent data store.
Note:
For linking user accounts from SP and IdP (Remote Identity Provider) together,
after logging in, the persistent nameID format must be on the top of the list.
Auth Context exact, minimum, Select the default context that you are planning to use for authentication and
Compare maximum, better what level of comparison do you want for authentication. The options are: exact,
minimum, maximum, better, none.
Auth Context This attribute maps the SAMLv2-defined authentication context classes to the
authentication level set for the user session for the service provider.
5. Click View Metadata against Service Provider. A new page opens, displaying the metadata
XML for the configured SP.
6. In the Authentication tab, select AR as the Authentication type.
7. Enter the following details.
Host Enter the Host Name of the BMC Remedy AR System server.
Port Enter the port number of the BMC Remedy AR System

server.

8. Click the Branding tab.

Customize Login Select this check box if you want to customize your login page. Click Preview to
Page view the page.
Window Title Enter a title for the browser window.
Product Name Enter a name for the product.
Company Logo Click the pencil icon to insert a company logo.
Background Image Click the pencil icon to insert a background image.
10. Click Add to add the realm details.
Related topics
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.
Distributed operations introduction (see page 1797)

Distributed operations components (see page 1803)
Implementing DSO (see page 1809)
Distributed operations scenarios (see page 1835)
Chained and broadcast distributed transfers (see page 1843)
Distributed Server Administration program (see page 1855)
Managing request IDs in distributed environments (see page 1857)
Overwriting all fields in duplicate requests (see page 1859)
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 (see page 1798)

Distributed updates (see page 1800)

Distributed returns (see page 1801)
Distributed deletes (see page 1802)
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 (see page 1803)) and by creating workflow to perform the
transfer (see Creating workflow to perform DSO operations (see page 1810)). 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 (see page 1836).
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 (see page 1829).
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.
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 (see page 4335)).
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 (see page 1805)) — 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 (see
page 1844).
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
Ownership automatically made to all other copies of the request in the ownership
chain (see Distributed updates (see page 1800)).
Independent Yes No Yes Cannot receive updates from the master copy because independent
Copy copies are outside the 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
Delete then deletes the original request.
Dynamic data, such as an entry in a defect-tracking form, is often modified at the site to which it is
transferred. Use a Data + Ownership operation to transfer this type of data.
Static data, such as customer biographical information, is typically not modified at the site to which
it is transferred. Use a Data Only or Independent Copy operation to transfer this type of data.
Distributed updates
A distributed update keeps all copies of a request in an ownership chain synchronized with the
master copy (the request with ownership). Modified information in the master request is
automatically sent to other requests in the chain at a specified time interval: daily, hourly,
immediately, or whenever ownership of the request is returned.
For example, suppose you have a broken keyboard. You submit a replacement request on the
sanfrancisco server. Because the chicago server handles office equipment replacements, the
sanfrancisco server uses a Data + Ownership distributed transfer to send the request to the
chicago server. This creates an ownership chain between the sanfrancsico and chicago copies
of the request. After the keyboard is replaced, the status of the master request on the chicago
server is changed to Completed. Because the distributed mapping between the forms is configured
to update the other copies in the ownership chain immediately, this change triggers the DSO to
update the status of the copy on the sanfrancisco server.

Consider the following factors when deciding whether distributed updates are required:
When distributed transfers occur between two forms whose requests are static, the copy on
the source server probably does not need to be updated because the master request does
not change after it is transferred. For example, Data Only and Independent Copy transfers
usually fit this criteria.
If users at the target site modify the master request and users at the source site need those
modifications, copies in the ownership chain should be updated. For example, Data +
Ownership transfers usually fit this criteria.
The following figure shows the basic flow of a distributed update. (The request in the darker form
has ownership after the operation is completed.)
Distributed update flow
For an example of how to set up a distributed update, see Distributed update scenario (see page
1840).
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 (see page 1841)
.
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 (see page 1799).

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 (see page 1842
).
Distributed operations components

This section contains information about configuring distributed operations using these elements:
Distributed mapping (see page 1803)

Distributed logical mapping (see page 1804)
Distributed fields (see page 1805)
Distributed pools (see page 1809)
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 (see page 1815).
You can also override settings in a mapping for a particular distributed operation. See Overriding
mapping settings on a per-request basis (see page 1808).
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 (see page 1807)

Advanced distributed fields (see page 1808)
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
(see page 1799)). 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 (see page )).
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 (see page 1819).
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.
Indicates whether a request holds ownership. (The copy of a request that has ownership is called the master copy.)
Master
Flag
From Specifies the ID of the request in the source (From) form.

Request
ID
Specifies the form from which a request was transferred. Also called the source form.
From
Form

From Specifies the server from which a request was transferred. Also called the source server.
Server
Specifies the distributed pool on the source (From) server that processed the distributed operation.
From
Pool
Full distributed fields

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 (see page )).
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.
Full distributed fields
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
Mapping is disabled, the distributed operation fails.
Specifies the mapping that was used during a transfer to create this request. Only DSO can set the value of this field.
From
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
Server for a mapping based on their values. If no mapping to the specified server exists, the distributed operation fails. Also
called the target server.
Mapping Contains a history-tracking record created at the time of transfer. The record includes the date and time of transfer,
History the source request ID, the source form, the source server, and the name of the specific mapping used. The result is a
record of all transfers to this request. Only DSO can set the value of this field.
Note: By default, this is an unlimited-length character field. If you set a maximum length for this field, records might
be truncated.
Current 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
Server this field.

Advanced distributed fields

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 (see page ).
Advanced distributed fields
Specifies the frequency with which to update the original request if a transferred copy is updated. See When to
Update (see page 1817).
When to
Update
Transfer Specifies the type of transfer to perform. Valid transfer types are Data Only, Data + Ownership, Independent
Mode Copy, and Copy + Delete. See Types of distributed transfers (see page 1800).
Duplicate Specifies the action that occurs if you transfer a request and the To form already contains a request with the
Request ID same request ID. See Duplicate Request ID Action (see page 1808).
Action
Max Time to Specifies the maximum times a distributed operation is retried before the system cancels the operation. See
Retry Retries (see page 1819).
Enforce Specifies whether to enforce patterns defined in fields on the target form during distributed operations. See
Pattern Enforce Pattern Matching (see page 1818).
Matching
Require Specifies whether to require values in fields defined as required fields on the target form. Use this field to enable
Required transfer of an entry with a NULL value in a required field. See Require Required Fields (see page 1818).
Fields
Matching Specifies the qualification to use to match a source request with a request in the target form. See Default
Qualification distributed pool (see page 1809).
For more information, see #Adding distributed fields to forms (see page ).
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 (see page ).)
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 (see page 1803)). 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 (see page 1810)).
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 (see page 1824).
Implementing DSO
This section contains information about working with distributed fields, mappings, and pools. It also
explains how to administer data transfers between forms.

Adding distributed fields to join forms (see page 1810)

Creating workflow to perform DSO operations (see page 1810)
Enabling distributed fields (see page 1813)
Enabling distributed mappings (see page 1814)
Enabling distributed pools (see page 1824)
Enabling logical mappings (see page 1828)
Managing pending distributed operations (see page 1829)
Performing distributed operations on join forms (see page 1833)
Setting up distributed operations (see page 1834)
To configure BMC Remedy Distributed Server Option (DSO), you need the appropriate
permissions. See Access control (see page 1273).
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 (see page ) and Reserved fields (see
page 2569).
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 (see page 1810)

Configuring DSO Return actions (see page 1812)
Configuring DSO Delete actions (see page 1812)
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 (see page 1815)) 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 (see page 2721)).

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.
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 (see page ).
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 (see page 1809) and Enabling distributed pools (see page 1824).
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 (see page 1847).

Configuring DSO Return actions

Use distributed returns to request the return of ownership from the form where ownership was
transferred. See Distributed returns (see page 1801).
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
(see page 1809) and Enabling distributed pools (see page 1824).
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 (see page 1847).
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 (see page 1802).
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.
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 (see page 1809) and Enabling distributed pools (see page 1824).
Warning
To ensure that DSO actions are executed in the correct order, assign all
related DSO actions to the same distributed pool. For example, all DSO
actions associated with the same form should use the same distributed
pool.
Server — The physical name or the logical name of the server on which the form
containing the specified request resides.
Form — The name of the form containing the specified request.
Enabling distributed fields

This topic explains how to add distributed fields to and delete them from forms.
Adding distributed fields to forms (see page 1813)

To add distributed fields to forms (see page 1813)
Deleting distributed fields from forms (see page 1814)
To delete distributed fields from forms (see page 1814)
For an overview of distributed fields, see Distributed fields (see page ).
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 (see page 1806).
Full — See Full distributed fields (see page 1807).
Advanced — See Advanced distributed fields (see page 1808).
4.
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 (see page 1813
) to the other form views as follows:
a. Open another form view.
b. Select Form > Add/Remove Fields on View.
c. In the Add/Remove Fields in View dialog box, move the distributed fields from the
Fields Not in View list to the Fields in View list.
If you do not select individual views, the distributed fields are added to all form views
by default.
6. (Optional) Rearrange the distributed fields on the form.
Deleting distributed fields from forms

Use the following procedure to delete some or all distributed fields from a form.
Warning
When you delete a field on a From (source) form that is mapped to a field on a To (target)
form, you also delete the mapping to the target field. If the target field is optional, only
data transferred between the two fields is affected. If the target field is required, the entire
transfer operation fails.
To delete distributed fields from forms
1. In Developer Studio, open the appropriate form.

3. In the Add Distributed Fields dialog box, do one of the following:
To remove only the advanced fields, select Full.
To remove the advanced and full fields, select Basic.
To remove all distributed fields, select None.
4. Click OK.
Enabling distributed mappings

This section contains information about creating, modifying, copying, and deleting distributed
mappings.
How distributed mapping is selected (see page 1815)

Creating distributed mappings (see page 1815)

Managing distributed mappings (see page 1822)
For an overview of distributed mappings, see Distributed mapping (see page 1803).
For an example of how to create a distributed mapping, see Distributed operations scenarios (see
page 1835).
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
Server (source) mappings are listed first in the order they were created. The first mapping in the list is
and To form selected.
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
Server escalation mappings are listed first in the order they were created. The first mapping in the list is
and To selected.
Form
5 From Distributed A list of mappings is generated from all distributed mappings on the server whose From
Form mapping Form value matches the name of the source form. Default mappings are listed first in the
order they were created. The first mapping in the list is selected.
Creating distributed mappings

Setting up automatic mapping (see page 1819)

Using the excluded fields option (see page 1820)
Creating custom mapping (see page 1821)
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
Mapping escalation does not specify a mapping, the default mapping is used. See Creating workflow to perform DSO
operations (see page 1810). 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
Name 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 (see page 1828).
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 (see page 542).
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.
Specifies that the mapping can use any server in the group as the From server. See Configuring DSO for a
server group (see page 351). Available only when the server is in a server group.
Note

Allow When you select this option, the From Server Name field must contain the server name alias, which
Any is specified in the Server-Name option of the AR System server configuration file.
Server
in
Server
Group
Form Specifies the name of the form from which the distributed operation is initiated (the source form). Enter the
Name form name, or click 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
Name operations occur (the target server). You can enter or select any server on which you are a valid user. You
can also select a logical server name that has already been defined. To create or edit a logical mapping, see
Enabling logical mappings (see page 1828).
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 name, or click the ellipsis button to use the Form Selector.
4. In the Save Distributed Mapping As dialog box, enter a name for the mapping.
Distributed mapping names can include up to 80 characters, including spaces. In the
Options panel of the Distributed Mapping editor, enter the following information, then save
your changes.
Field Description
Specifies the update frequency for the original request if a copy transferred with ownership is updated:
When to Daily — At two minutes past midnight.
Update Hourly — At two minutes past the hour.
Immediately — Right after the copy is changed.
No Update — Never.
On Return — Only when ownership is returned.
Specifies the type of transfer to perform:

Transfer Copy + Delete — Transfers an independent copy of the request with ownership. If successful,
Mode 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 (see page 1799).
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 (see page 1800).
Note

At a minimum, to transfer ownership, the form must have the basic distributed fields (see page
1805).
Specifies the action that occurs if you transfer a request and the target form already contains a request
Duplicate with the same request ID:
Request ID Create New — A new request is created on the target server for the transfer.
Action 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 (see page ).)
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.
Specifies whether to enforce patterns defined in fields on the target form:

Enforce Yes — The target system pattern checks data sent to the target form. Data transferred to fields on
Pattern the target form must follow pattern attributes defined in mapped fields on the target form.
Matching 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 (see page 2646).
Specifies whether to require values in fields defined as required fields on the target form:
Require Yes — The target system does not allow NULL entries in required fields on the target form.
Required Optional fields on the source form must contain data if they are mapped to required fields on the
Fields 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
Request ID form:
Selected — Distributed transfers are performed when the request ID in the target form matches
the request ID in the source form.
Cleared — Target and source data are matched according to the qualification entered in the
following Matching Qualification field.
For example, if you do not want to use server-specific request ID prefixes to distinguish the requests
from one another, you can use this method (see Preventing duplicate request IDs (see page 1858)). In
this case, use a different data field that uniquely identifies each request to match a target request with a
source request.
Matching
Qualification

When the Match by Request ID check box is not selected, specifies the qualification to use to find the
correct entry in the target form. If you match by qualification, all form definitions used in the qualification
should be on the From (source) server. A unique index should be created on the field used to distinguish
requests. For more information about qualifications, see Building qualifications and expressions (see
page 2748).
Specifies the maximum number of times a pending item is retried before the system cancels the item:
Retries 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 (see page ).
5. In the Transfer to Target panel of the editor, specify how the data in a source form is
mapped to a target form for a transfer.
See these sections:
6. In the Return from Target panel of the editor, specify how the data in a target form is
mapped to a source form for an update or a return.
See these sections:
7. To view, add, and edit Help text for the distributed mapping, use the Help Text property in
the Properties tab.
In most cases, the Help text is simply a description of the mapping. Only AR System
administrators and subadministrators who have the mapping open in the Distributed
Mapping editor can view and edit the Help.
See the definition for "Help Text" in Field properties (see page 2646).
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 (see page 2646).
Setting up automatic mapping

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
(see page 1815).
To set up automatic mapping
1. Open the distributed mapping in the Distributed Mapping editor.

2. In the Transfer to Target or Return from Target panel, click Auto Map.
3. In the Auto Map dialog box, select an automatic mapping method:
Match IDs — Maps fields on the source form to fields on the target form that have
the same field IDs. If you later add fields with matching IDs to both forms, BMC
Remedy AR System automatically maps them to each other.
Match Names — Maps fields on the source form to fields on the target form that
have the same field names. If you later add fields with matching names to both forms,
BMC Remedy AR System automatically maps them to each other.
4. To prevent BMC Remedy AR System from mapping certain fields, select the fields in the
Auto Map table's Field column, and click Remove.
5. Click OK.
The mapped fields appear in the table on the Transfer or Return panel.
Note
If you are not creating mapping between identical forms, ensure that no unwanted
unmapped fields exist on the forms.
6. To customize any of the mappings listed in the table or to add custom mappings, see
Creating custom mapping (see page 1821).
Using the excluded fields option

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 Distributed Mapping editor is correctly specified. See Creating distributed mappings
(see page 1815).

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.
Creating custom mapping

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 Distributed Mapping editor is correctly specified. See Creating distributed mappings (see
page ).
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 (see page 1821):
Field in the From (source) form
Keyword

6.
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 (see page ).
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 (see page 2788).
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 (see page 1821) through 6 (see page 1821) 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 (see page 1823)

To modify a distributed mapping (see page 1823)
Copying distributed mappings (see page 1823)
To copy a distributed mapping (see page 1823)
Deleting distributed mappings (see page 1824)
To delete a distributed mapping (see page 1824)

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 (see
page 1813).
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 (see page 1853).
To copy a distributed mapping

3.

5. Double-click the distributed mapping that you want to copy.
The distributed mapping appears in the Distributed Mapping editor.
6. Select File > Save As.
7. In the Save Distributed Mapping As dialog box, enter a name for the new distributed
mapping.
8. Click OK.
The new distributed mapping is listed on the Distributed Mappings tab.
Deleting distributed mappings

The delete operation cannot be undone. Make sure that you no longer need a mapping before
deleting it. You cannot delete open distributed mappings.
To delete a distributed mapping

5. Select the distributed mapping that you want to delete.
6. Select Edit > Delete.
The distributed mapping is deleted from the server, and its name is removed from the
Distributed Mappings tab.
Enabling distributed pools

This section contains information creating and modifying distributed pools:
Creating distributed pools (see page 1825)

Managing distributed pools (see page 1826)
Setting polling intervals for distributed pools (see page 1827)
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 (see page 1853).

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
Pool distributed operation. See Default distributed pool (see page 1809).
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 (see page ).
Interval If the Polling check box is selected, specifies the interval, in minutes, at which the pool queries the distributed
(mins) pending queue.
Minimum interval is 5 minutes (default).
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 (see page ).
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 (see
page 4378).)
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
(see page 4335)). 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 (see page 2646).
8. Select File > Save, then restart the DSO server.
Managing distributed pools

In this topic:
Modifying distributed pools (see page 1826)

Copying distributed pools (see page 1826)
Deleting distributed pools (see page 1827)
To delete a distributed pool (see page 1827)
Modifying distributed pools

4. In the All Objects list, double-click Distributed Pools.
The Distributed Pools tab appears in the object lists area. The tab lists the distributed
5. Double-click the distributed pool that you want to modify.
The distributed pool appears in the Distributed Pool editor.
6. Modify the pool as necessary.
For information about the fields in the editor, see Creating distributed pools (see page 1825).
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.
6. Select File > Save As.
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.
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 (see page 1825).
Default pool and polling

When a distributed pool is disabled, the operations associated with it are processed by the default
pool. If the default pool is a polling pool, the operations are not immediately processed. Consider
this when setting up your pools.

Enabling logical mappings

This section contains information about creating, modifying, copying, and deleting distributed
logical mappings:
Creating logical mappings (see page 1828)

Managing distributed logical mappings (see page 1828)
For an overview of distributed logical mappings, see Distributed logical mapping (see page 1804).
Creating logical mappings

You can define logical mappings for each server name involved in a transfer, return, or delete
action. While moving the distributed mappings from the development environment to the
production environment, this feature eliminates the need to manually replace the server names in
any distributed mapping. At run time, DSO replaces the logical server name with the physical
server name in accordance with the mappings in the Distributed Logical Mapping form.
You can also create a mapping to define a logical name for a field whose value is not known at the
time the distributed mappings are being developed. While moving this mapping to production
environment, you can change the value of the physical name with the actual value for this field in
the Distributed Logical Mapping form. This ensures that the mapping works properly for your
production environment.
To create a distributed logical mapping
1. In a browser, open the AR System Administration Console, and click System > Distributed
Server Option > Distributed Logical Mappings > New request.
2. Enter the following information:
Logical Name: Specifies the name of the logical entity (server or field name) defined
in the distributed mapping
Physical Name: Specifies the name of the actual entity (server or field name) where
the user wants to use the distributed mapping
Logical Server Name: When selected specifies that this logical name is for a server.
This is required only if you want to select the name of the logical server in the Server
Name box either in the Distributed Mapping editor or the DSO action editor in BMC
3. Click Save.
Managing distributed logical mappings

In this topic:
Modifying distributed logical mappings (see page 1829)

Deleting logical mappings (see page 1829)
To delete a distributed logical mapping (see page 1829)

Modifying distributed logical mappings
Server Option > Distributed Logical Mappings > Search.
2. From the results list, select the item to modify.
3. Modify the mapping as necessary.
4. Click Save.
Deleting logical mappings

The delete operation cannot be undone. Make sure that you no longer need a mapping before
deleting it.
To delete a distributed logical mapping
Server Option > Distributed Logical Mappings > Search.
2. From the results list, select the item to delete.
3. Click Delete.
Managing pending distributed operations

This section contains information about managing items in the pending distributed queue:
Viewing items in the pending distributed queue (see page 1829)

Removing items from the distributed pending queue (see page 1830)
How errors affect pending items (see page 1830)
Handling duplicate pending items (see page 1831)
Logging failed pending items (see page 1832)
Retrying failed pending items (see page 1833)
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 (see page 1830).)
For information about when polling DSO servers and pools check for requests, see these sections:
Setting a polling interval for the DSO server (see page 1830)
Setting polling intervals for distributed pools (see page 1827)

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 (see page 1832).)
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 (see page 544).)
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 (see page 1815).
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 (see page 543).
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 (see page 4335).
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 (see page 4335).
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 (see page 1833):
a. Select Retry.
b. Click Save.
If you selected multiple items in step 3 (see page 1833):
c. Select Actions > Modify All.
The Details pane changes to Modify All mode, and a blank form is displayed.
d. In the blank form, select Retry.
e. Click Save.
f. In the confirmation message, click Yes.
The specified items are removed from the Distributed Pending Errors form and re-
added to the Distributed Pending form. They are retried as follows:
If a polling interval is set for the local DSO server, the item is retried when the
polling interval expires. (See Setting a polling interval for the DSO server (see
page 1833).)
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 (see page 1827).)
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 (see page 1833).)
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 (see page 538).
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 (see page 2375).
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 (see page 535).
2. Determine which forms you will transfer data from and which forms you will transfer data to.
3.
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 (see page 1800).
How often should requests be updated on a server?
See the definition for "When to Update" in Creating distributed mappings (see page
1815).
How should duplicate request IDs be handled?
See Managing request IDs in distributed environments (see page 1857).
Will you need to override distributed mapping settings on a per-request basis?
See Overriding mapping settings on a per-request basis (see page 1808).
4. Determine which distributed fields to add to the forms identified in step 2 (see page 1834).
See Distributed fields (see page 1805).
5. Add distributed fields to the forms identified in step 2 (see page 1834).
See Adding distributed fields to forms (see page 1813).
6. Determine whether you will use distributed pools.
See Distributed pools (see page 1809).
7. (Optional) Create distributed pools according to your analysis in step 3.
See Enabling distributed pools (see page 1824).
8. Determine how to map the forms identified in step 2 (see page 1834).
See Distributed mapping (see page 1803).
9. Create the required distributed mappings.
See Creating distributed mappings (see page 1815).
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 (see page 1843).
10. Create filters or escalations that define the conditions under which distributed operations
occur.
See Creating workflow to perform DSO operations (see page 1810).
11. (Optional) Employ some of these advanced functions:
Setting up chained distributed transfers (see page 1844)
Setting up broadcast distributed transfers (see page 1851)
Distributed operations scenarios

Distributed transfer scenario (see page 1836)

Distributed update scenario (see page 1840)

Distributed return scenario (see page 1841)

Distributed delete scenario (see page 1842)
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 AW (Acme West)

Francisco 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 (see page 1837).
2. Create distributed mappings for the Acme bug tracking forms (see page 1837).
3. Create a filter with a DSO Transfer action on the From server (see page 1839).
4.
4. Test the distributed mapping (see page 1840).
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 (see page ).
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 Acme East Bug

Tracking 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 (see page 1837).
7. Save the form.
8. Repeat step 2 (see page 1837) through step 7 (see page 1837) 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 (see page ).
To create distributed mappings for the Acme bug tracking forms
1. In Developer Studio, select File > New > Distributed Mapping.
2.
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:
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 (see page 1838) and step 5 (see page 1838).
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 (see page ).
To create a filter with a DSO Transfer action on the From server
1. In Developer Studio, select File > New > Filter.

2. Select the From (sanfrancisco) server, and click Finish.
3. In the Associated Forms panel of the Filter editor, click Add.
4. In the Form Selector, select the Acme West Bug Tracking form, and click OK.
5. In the Execution Options panel, set the options shown in the following figure:
Filter editor — Execution Options panel

5.
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 (see page 1800)).
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 (see page ).
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 (see page 1837).
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 (see page 1837).)
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 (see page ).
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 (see page 1800)).
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 (see page 1799).

To configure a distributed delete operation on the To server

2. Select the To (chicago ) server, and click Finish.
3. In the Associated Forms panel of the Filter editor, click Add.
4. In the Form Selector, select the Acme East Bug Tracking form, and click OK.
7. In the Type list in the DSO panel, select Delete.
8. Fill in the other fields as shown in the following figure, then select File > Save.
Filter editor — DSO Delete action
9. In the Save Filter As dialog box, enter a name for the filter, such as Acme Bug Distributed
Delete, then click OK.
Now, when a request is deleted from the Acme West Bug Tracking form, this DSO action
deletes the request with the same Request ID in the Acme East Bug Tracking form on the
chicago server.
Chained and broadcast distributed transfers

Setting up chained distributed transfers (see page 1844)

Setting up broadcast distributed transfers (see page 1851)
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 (see page )). 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 (see page
).
Setting up chained distributed transfers

Testing chained distributed mappings (see page 1847)

Avoiding infinite loops (see page 1847)
Creating mapping chains (see page 1849)
Managing chained distributed transfers (see page 1850)
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 (see page 1813).
Add distributed mappings and filters to the sanfrancisco and chicago servers
according to the procedures in Distributed operations scenarios (see page ).
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:

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 (see page ).
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:
Controlling updates (see page 1850)

Controlling returns (see page 1850)
Deleting requests (see page 1851)
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 (see page )).
For more information, see Distributed deletes (see page ).
Setting up broadcast distributed transfers

In this topic:
Broadcasting distributed mappings and pools (see page 1853)
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 (see page ).
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 No
Update Update
Transfer Mode Data Only
See Creating distributed mappings (see page ) and Distributed transfer scenario (see
page ).
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:

2.
Field Value
When to No
Update Update
Transfer Mode Data Only
page ).
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 Acme ProdInfoArch W to
1 E
Action Acme ProdInfoArch W to

2 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.
See Creating workflow to perform DSO operations (see page ).
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 sanfrancisco

field

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

field
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)
page ).
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 Distributed Mapping: sanfrancisco to chicago
1
Action Distributed Mapping: sanfrancisco to toronto

2
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.
See Creating workflow to perform DSO operations (see page ).
4.
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 (see page 1853) through step 4
(see page 1854) for the Distributed Pool form.
Distributed Server Administration program

In this topic:
Overwriting distributed fields scenario (see page 1857)
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 ownership.
-m
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 Acme ProdInfoArch W to E

Mapping
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 (see page 1857).
2. Change to the ARSystemServerInstallDir directory containing ardist.
3. At the prompt, enter this command:
ardist -i <ARSystemServerInstallDir> -c "Acme West Bug Tracking"

-e 1234567 -M -p "Acme ProdInfoArch W to E"
-r sanfrancisco -s "Acme Product Info Archive" -x chicago
Managing request IDs in distributed environments

In this topic:

Preventing duplicate request IDs (see page 1858)

Handling duplicate request IDs (see page 1858)
Using qualifications to match requests (see page 1858)
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 (see page ).
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 (see page ).
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 (see page ).
For example, matching qualifications are useful when you do not want to use request ID prefixes to
distinguish requests from one another. In this case, use a data field other than Request ID that
uniquely identifies each request. BMC Remedy AR System can use that field to match a request in
the target form (if one exists) with one in the source form.

Note
You should create a unique index on the data field used to distinguish one request from
another.
Overwriting all fields in duplicate requests

When you specify the Overwrite action for handling duplicate request IDs (see Duplicate Request
ID Action (see page 1818)), 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 (see page ).
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. Save the AR System server configuration file.

5. Restart the BMC Remedy Action Request System Server serverName service.
Capturing server events for workflow or API

calls
The Server Events form enables you to capture server-related activities and use them in workflow
and API programs. You can select the server events that you want to record, search and view the
returned entries, and create workflow to notify companion servers and interested clients of server
changes that might affect them. To access this form, in a browser, open the BMC Remedy AR
System Administration Console, and click System > General > Review Server Events.
Note
For information about setting Server Event options, see Setting server logging options
(see page 272).

Understanding the Server Events form (see page 1860)

How the Server Events form is created (see page 1860)
Types of events you can record (see page 1861)
Viewing the server changes you recorded (see page 1862)
Using server events in workflow (see page 1877)
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 (see page ).
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 (see page 489).
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 (see page 272).
The Server Events form is similar to other BMC Remedy AR System forms. You can add fields and
workflow to it, but you cannot delete the reserved fields, which are discussed in the following
section.
How the Server Events form is created

The Server Events form is created automatically by the server and contains the following reserved
fields:
800 AR_RESERV_SVR_EVENT_TYPE
801 AR_RESERV_SVR_EVENT_CAUSE
802 AR_RESERV_SVR_EVENT_DETAILS_1

These fields distinguish the Server Events form from all other forms. Only one Server Events form
can exist in the AR System database; therefore, only one form contains these reserved fields.
The Server Events form can be created as follows:
Case 1: When the server starts, the server creates the Server Events form automatically if
the form does not already exist in the BMC Remedy AR System database. If you delete the
Server Events form, the server automatically regenerates the form the next time the server
is started.
Case 2: If you create your own Server Events form, you must supply default values with the
correct data type for the required core fields. If the Server Events form already exists and
you try to create a form with the reserved fields, the server returns an error when you try to
save the form. Error checking does not allow the existence of more than one Server Events
form.
You can modify the Server Events form by using BMC Remedy Developer Studio or a driver. You
can rename the Server Events form; however, if any of the reserved fields is removed, the form is
no longer a valid Server Events form.
Types of events you can record

The following table lists the types of server events you can record.
Events you can record
Object Example For more information
Changes to server objects (such as forms, filters, The AR System server records the API calls Viewing server object
active links, escalations, fields, VUIs, char that cause server object changes changes (see page 1863)
menus, and containers)
Changes to users, groups, applications, and Viewing user, group,

roles User added, modified, or deleted using application, and role
the User or Group form changes (see page 1865)
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 Alert users when server settings change Viewing server setting
changes (see page 1867)
Alert registration Alert users who are registered or deregistered Viewing alert registration
activity (see page 1874)
Archive activity Alert users of archive activity Viewing archive activity

(see page 1875)
Server group activity A server in a server group fails and another Viewing server group
server takes over actions (see page 1876)

Object Example For more information
Client Timeout A client timed out before the server could Viewing client timeout
respond. server event details (see
page 1877)
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 15
AR_SVR_EVENT_SERVGROUP_ACTION
#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 (see page 1863)

Viewing user, group, application, and role changes (see page 1865)
Viewing server setting changes (see page 1867)
Datatypes values (see page 1874)
Viewing alert registration activity (see page 1874)
Viewing archive activity (see page 1875)
Viewing server group actions (see page 1876)
Viewing hierarchical group actions (see page 1876)
Viewing client timeout server event details (see page 1877)
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 Event Details 3
2
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 ARSetField field ID; field name form name old form name
13
2 1 or ARCreateField field ID; field name form name

14
2 43 ARDeleteField field ID; field name form name
2 56 ARDeleteMultipleFields field ID; field ID; ...; field form name

ID
2 151 ARCreateMultipleFields field ID; field ID; ...; field form name
ID
2 152 ARSetMultiple Fields field ID;field ID;...;field ID form name
3 0 or ARSetCharMenu menu name old menu name

17
3 1 or ARCreateCharMenu menu name

18
3 19 ARDeleteCharMenu menu name
4 0 or ARSetFilter filter name old filter name

22
4 1 or ARCreateFilter filter name

23
4 24 ARDeleteFilter filter name
5 35 ARImport

Type Cause Cause Description Event Details 1 Event Details Event Details 3
2
6 0 or ARSetActiveLink active link name old active link

39 name
6 1 or ARCreateActiveLink active link name

40
6 41 ARDeleteActiveLink active link name
7 0 or ARSetEscalation escalation name old escalation

49 name
7 1 or ARCreateEscalation escalation name

50
7 51 ARDeleteEscalation escalation name
8 0 or ARSetVUI vui ID;vui name form name old vui name

63
8 1 or ARCreateVUI vui ID;vui name form name

64
8 65 ARDeleteVUI vui ID;vui name form name
9 0 or ARSetContainer container name old container name

75
9 1 or ARCreateContainer container name

76
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.
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 entry ID;group name

modified
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 (see page ).)
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 AR_DATA_TYPE_CHAR
String
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 Operation type tag (R);byte length of user name;user name;registration time;IP address of client;
in to alert client port;actual client IP address;server IP address that client expected;registration flag;client
client version;client codeset
13 103 User logs Operation type tag (U);byte length of user name;user name;IP address of client;client port;client
out from version
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 1 Details 3
14 1 Copy to archive only Source <Actual number of entries copied to archive> of <Total Destination
form number of matches> form name
name
14 2 Delete from source Source <Actual number of entries deleted from source> of <Total Destination
only form number of matches> form name
name

Type Cause Cause Description Event Event Details 2 Event

Details 1 Details 3
14 3 Copy to archive and Source <Actual number of entries copied to archive and deleted Destination
delete from source form from source> of <Total number of matches> form name
name
Viewing server group actions

The following information appears in the fields on the Server Events form when a server group
activity is recorded:
Event Type: 15
Event Cause: Failover (1), relinquish (2), takeover (3)
Event Details 1: Server performing action
Event Details 2: Name of operation
Event Details 3: Other server
Submitter: User who caused the server group action event
The following table describes specific details of server group actions.
Server group actions
Type Cause Cause Description Event Details 1 Event Details 2 Event Details 3
15 1 Server in group fails over an Server that an Name of the Server that an operation is
operation operation is failing over operation failing over from.
to. involved.
15 2 Server in group is Server relinquishing an Name of the Server expected to take over a
relinquishing an operation operation. operation relinquished operation.
involved.
15 3 Server in group takes over Server taking over an Name of the Null
an 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
Type Cause Cause Description Event Details 1 Event Event

Details 2 Details 3
17 1 A group command is Schema for which the groups are being Null Null
initiated initiated
17 2 A group command is Schema for which the groups are being Null Null
completed completed
Viewing client timeout server event details

The information provided in the Server Event form is tailored to notifications, with fields that can be
easily used in the qualification and as substitution parameters in the notification text. The following
table shows Server Event form field mapping for the client timeout event:
Field Name Value
Submitter User who experienced the timeout
Event Type 19 (#define AR_SVR_EVENT_CLIENT_TIMEOUT 19)
Event Cause Result code of the API call (0 for no error)
Event Details 1 API call name (for example, ArGetListEntryWithFields)
Event Details 2 Read-only call indicator (0 for API call that updates, 1 for read-only API, in character
format)
Event Details 3 Form name if the API call involves a form; otherwise, NULL
Using server events in workflow

Recording server events enables you to communicate internal (non-data) server changes to
processes outside the server and to use workflow to notify companion servers or interested clients
of changes that affect them.
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 (see page 1141).
Managing data
This section contains information about managing your data in BMC Remedy AR System, including
exporting and importing data and definitions, and the AR System database.
Auditing data (see page 1878)

Archiving data (see page 1895)
File types used in migrations (see page 1912)
Integrating and migrating data (see page 1914)
Importing data into BMC Remedy AR System forms (see page 1969)
Importing and exporting Flashboards objects (see page 1980)
Exporting and importing data and definitions (see page 1981)
Using the Request ID to improve performance or security (see page 2006)
Understanding the AR System database (see page 2019)
SQL definitions of the data dictionary tables (see page 2051)
Auditing data
The following topics provide information about auditing:
Auditing changes to data (see page 1878)

Supporting compliance audits with BMC Remedy Approval Server (see page 1891)
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
(see page 1879)or a log-style audit (see page 1882). 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 (see page 1879)

Log-style audits (see page 1882)
Configuring auditing (see page 1884)
Considerations for auditing forms (see page 1887)
Assignee Group and other dynamic group fields (see page 1890)
Using flag fields to view changes to an individual field (see page 1890)
Audit processing and filters (see page 1891)
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 (see page 1880)

Audit form fields (see page 1881)
Deleting an audit form using an API call (see page 1882)

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 (see page ).)
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 The Request ID of the entry being audited.

ID
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 (see page 1883).)
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 (see page 1883)

Log keys (see page 1884)
Log form characteristics (see page 1884)
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 The Request ID of the form being audited.

ID
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 (see page 1882) 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 (see page 1883).)
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 (see page 1884)

Specifying fields to be audited (see page 1885)
Table fields in audit forms (see page 1886)
Changing character field properties on the main form (see page 1886)
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.
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 (see page 291)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. 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 (see page ) for more information.
2. Select the fields you want to audit.
3. In the Properties tab, set the value for the Audit Option property.
The options are:
None — Changes to this field are not recorded by any audit processing.
Audit — Changes to this field trigger audit processing and its new value is recorded
in the audit form or log form, depending on the audit style you specified at the form
level. If the value does not change, its value is not recorded.
Copy — The database value or the value in the current transaction if present is
recorded during an audit, but does not trigger audit processing.
Audit and Copy-Changes to this field trigger audit processing. If the value has not
changed, the value from the database is recorded (similar to the behavior of the Copy
option).
4. (For log-form audits only) In the Properties tab, set the values for the Audit Log Key
property:
Key 1 — The value of this field appears in the Log Key 1 field in the log form.
5. Save the form.
Table fields in audit forms

If a form is enabled but has auditing disabled and has no audit form, the BMC Remedy AR System
server tries to create an audit form for it. If the main form has a table field, the BMC Remedy AR
System server tries to create the table field in the audit form while creating it. If the table field's
form is missing, the audit form is not created, and you receive the following errors:
Could not create the Archive or Audit Form specified. Archive/Audit for this form has
been disabled. (ARWARN 8992)
Form does not exist on server Form1: (ARWARN 303).
The problem is that the BMC Remedy AR System server is attempting to create the table field in
the audit form, but because the table field's form is missing, it cannot pass the validation.
To resolve this problem, create the table field's form, or delete the table field from the main form.
Changing character field properties on the main form

When you modify the following properties of character fields on the main form, the BMC Remedy
AR System server updates the audit form:

Attributes
Field limits
Display properties
Help text
When you modify the following properties, the audit form is unchanged:
Entry mode
Index for FTS
Permissions
Fields on audit forms are always read-only.
Considerations for auditing forms
View and vendor forms
When vendor or view forms have form-style auditing, the audit form created is a regular form,
which includes core fields. Therefore, you might have to provide default values for the Short
Description and Submitter fields because they are required fields (for example, if you have
workflow configured for the audit form).
Join forms
Both form-style and log-style auditing are available for join forms. An audit of a join form is
triggered if the join form contains audit fields from the base forms and the audit qualification (if
present) is TRUE.
Form style
For a form-style audit, the join forms' underlying forms must also be configured for form-style audit
and must be enabled. BMC Remedy AR System creates the join forms' audit form as a join form of
the underlying forms' audit forms and use the Audit Join Key fields in the join criteria, as shown in
How a join audit form is created

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
AR System server updates the audit form:
Attributes
Field limits
Help text
When you modify the following properties, the audit form is unchanged:
Entry mode
Display properties
Index for FTS
Permissions
Fields on audit forms are always read-only.

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
(see page 2938).
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 (see page 595).
The following topics provide information about how BMC Remedy Approval Server supports
compliance audits:
Enforcing business rules with approval processes (see page 1892)

Electronic signatures (see page 1893)
Elements of auditable processes (see page 1894)
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 (see page ).
For more information about access control in BMC Remedy AR System, see Access control (see
page 1273).
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 (see page 1894)

Signatures of approvers (see page 1894)
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 (see page 1724).
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 (see page 1341).
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 (see page 4308).
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 (see page 595).
Archiving data
The archive feature of BMC Remedy AR System provides a convenient way to periodically store
data (not definitions) from a form to an archive form; this reduces the amount of data accessed
during searches on the main form, thus improving system performance. Archiving applies to all
types of forms, except display-only and join forms. The main form is the form on which archive is
set (data is read from this form), and the archive form is the form to which data is copied.
The archive form is a regular form with special behaviors. It must be on the same server as the
main form.
When configuring a form for archiving, you can designate an existing form as the archive form if it
has the characteristics of an archive form. (See Characteristics of archive forms (see page ).) If
you do not enter the name of an existing form, BMC Remedy AR System creates the form.
The following archive types are available:
Copy to Archive and Delete from Source — The entries you choose from the main form
are copied to the archive form and deleted from the main form.
Delete from Source — The entries you choose from the main form are deleted; no archive
form is involved.
None — Select this option to delete the archive settings for the form. The form is not
archived.
This section provides the following topics:
Configuring data archiving for a form (see page 1896)

Configuring data archiving for a server (see page 1898)
Defining associations to follow (see page 1900)
Setting global archive interval for forms (see page 1904)
Exporting and deleting archive data (see page 1905)
Deleting an archive form (see page 1907)
Performing data operations with an AR_ARCHIVER user (see page 1907)
Changes to the main form that affect the archive form (see page 1908)
Characteristics of archive forms (see page 1909)
Managing the archiving process (see page 1911)

Related topic
Archiving concepts (see page 136)
Configuring data archiving for a form

You can use the data archiving feature to back up and delete data from forms.
Notes
Do not archive system forms (such as User, Group, Server Statistics, and Server
Events) by using the Copy to Archive or the Delete from Source option because
these forms use reserved fields that should exist only on one form in BMC Remedy
AR System.
You cannot archive join forms and vendor forms. Any existing archive defined for
join form and vendor form is ignored for archiving.
To configure data archiving for a form
Important
To make changes in the Age Qualification field, you must select the overlay type as
Overwrite.
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

4.
Delete from Source

None
For more information on Archive Types, see Archiving data (see page 1895).
Note
In version 9.0, archives must be of type copy and delete or delete. Any
archives that are of type copy at the time of upgrade will be converted to
copy and delete. This ensures that records in the archive form are unique.
5. Select the Enable option to enable archiving of the form.

6. Enter the name of the archive form to send the archive data. If the form does not exist, BMC
Remedy AR System creates the form.
7. If you selected Copy to Archive and Delete from Source, enter a name for the archive
form.
For example, if you are archiving data on the Application Statistics form, you might name
the archive form Application Statistics_Archive.
If the form that you entered does not exist, BMC Remedy AR System creates the form. If the
form exists, it must have these required properties of an archive form, as described in
Characteristics of archive forms (see page ).
8. To include the form in the archive policy, select the Include In Archive Policy option. When
you select this option, your form is archived as per your configuration based on the global
policy set in the Server Configuration form. For more information, see Archive policy in
archiving concepts (see page 137).
9. (optional ) If you selected Copy to Archive and Delete from Source, select the following
options to exclude them from the archive form:
No Attachments
No Diary Fields
Selecting these options saves space in the archive form if the main form has large
attachments or a large amount of data in diary fields.
Warning
If you select Copy to Archive and Delete from Source, and select the No
Attachments and No Diary Fields options, the data in the attachments and
diary fields are deleted from the main form and are not copied to the archive
form.
10.
10. To identify the data on the form to archive, enter a qualification.

For example, to archive statistics for a particular server from Application Statistics form,
enter:
'Server Name' = “server name”
11. To specify the age criteria for archiving records, enter the number of days and age
qualification field. The default qualification field is Modified Date. This is a new parameter
added in the archive definition, which specifies that the records should be archived when
they have reached a specific age. For information about understanding age qualification,
see Age qualification in archiving concepts. (see page 136)
For example, to archive statistics that were last modified before 30 days from the current
date in the Application Statistics form, enter:
Number of Days: 30
Qualification Field: Modified Date
12. The description fields in the archive policy form and Archive Manager Console show the
description from the archive definition. Write the description in such a way that even an
administrator less familiar with the application is able to understand the effects of the policy.
13. Save the form.
After the data is archived according to your qualification criteria at the time specified, you
can open your archive form and view archived data using a browser.
Important
When a view form is archived, the archive form is created as a regular form
containing core fields that are not in the source form. You must supply default
values for the required Submitter and Short Description core fields in the archive
form.

You must now choose which association you want your archiving process to include along with
your form. For more information, see Defining associations to follow (see page 1900).
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 (see page 342).
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.
Defining associations to follow

Associations help you in archiving related forms together. When you set archive on a form, defining
associations to follow allows you to archive all or specific related forms. For more information
about using associations, see Associations overview (see page 117).

To define associations that need to follow during form archive (see page 1901)
Association to follow example (see page 1902)
Before you begin
You must create all the relationships between the forms using associations object. For
information about creating associations, see Creating associations (see page 2296).

You must have configured your archive from the Archive panel in the Definitions tab of
that form. For information about configuring data archiving, see Configuring data archiving
for a form (see page 1896).
Note
Indirect associations having Many to Many cardinality cannot be followed for archiving.
Even if you select those associations, they will be ignored during the archiving process.
To define associations that need to follow during form archive
1. Open the form with which you want to archive.

3. Expand the Associations to Follow for Archive panel.
Note
You can only create Additive overlay type for the Association to follow for Archive
panel.
4. Select the option for defining associations that needs to be archived with the form. The list
displays the associations to follow options as per level of precedence .
Follow Parent — This option inherits parent settings. If you select this option, the
option specified for the parent form is applied to the child form. For example, if “All
Enforced” option is selected for the parent form, the child form also follows “All
Enforced” associations. For more information, see Association to follow example (see
page 1902).
None — No associations are selected to follow for archiving with this form. No related
forms will be archived.
Selected — Only the selected associations are archived. When you choose this
option, you can select the associations and the related forms that you want to
archive.
All Enforced — All enforced associations are followed for archiving. After you choose
this option, all enforced associations are automatically marked as selected in the
associations list. If required, unenforced associations can also be selected from the
associations list.
All — All the associations for this form are archived. Generally, this option is not used
for archiving. If you select this option, associations not meant for archiving are also
included.

Note
In the Best Practice Customization mode, you can overlay Associations to

Follow for Archive. However, you will only be able to select the association
to follow option which includes higher level option than Base Development
mode. For example, if you have defined Selected option in Base
Development mode, you can only choose All Enforced or All option in Best
Practice Customization mode.
5. Save the form.
Note
You can also view a list of associations which are not available for following as
they do not exist on the server which the form is defined.
You can also view a list of forms which should be archived along with this form.
However, if no archive is defined, these forms will not be archived. You can double-
click any such form and configure data archiving on it. For information about
archiving steps, see Configuring data archiving for a form (see page 1896).
While following association for archive, server will not archive data for a related
form, if archive is not defined for it. Also, in that case, server will not follow any of
the associations of the related form since it did not archive the data from related
form itself.
Association to follow example

The following image displays an example which will help you understand how associations are
followed during archiving.

Following table illustrates associations that will be followed and the forms that will be archived
depending on the Associations to follow for Archive setting defined for each form.
Form A Form B Form C Associations that will be followed Forms that will be
for archiving archived
Selected (AB, AC) Follow Follow Parent A, B, C

Parent AB
AC
All Enforced Follow Follow Parent A, B, D

Parent AB
BD
All Enforced Selected Follow Parent A, B, E

(BE) AB
BE
All Enforced (with AC Follow All Enforced or Follow A, B, C, D, F

selected) Parent Parent AB
AC
BD
CF

Form A Form B Form C Associations that will be followed Forms that will be
for archiving archived
Selected (AB, AC) None All Enforced A, B, C, F

AB
AC
CF
Selected (AC) All All A, C, F, G

AC
CF
CG
All Follow Selected (CG) A, B, C, D, E, G

Parent AB
AC
BD
BE
CG
All None All Enforced (with CG A, B, C, F, G

selected) AB
AC
CF
CG
Follow Parent All All - A
Setting global archive interval for forms

To set global schedule for archiving on the forms to be archived, you must configure archiving
interval on your server. Starting this release, you will not be able to set archive schedule for
individual forms using BMC Remedy Developer Studio. For more information about understanding
how archive interval works, see Archiving concepts (see page 137).
To set the global archive interval
Server Information.
2. Click the Configuration tab, and perform the following step:
a. Enter the Archive Interval value in hours. For example, if you enter value 2, all the
forms where you have enabled archiving, are archived after every two hours.
Note
The default value for Archive Interval is 24 hours.
3. Click Apply to confirm the changes.
4.
Note
You can also set the global archive interval by using the Run Every (hours) field from
AR System Archive Manager Console. For more information, see Changing how often the
archiving process runs.
Related topics
Archiving overview (see page 134)
Archiving concepts (see page 136)
Exporting and deleting archive data

You can manage your production system efficiently by periodically extracting archive data (for
example, archive data which is more than 5 years old). Using this feature, you can efficiently
manage the production system and optimally utilize the available infrastructure and resources. You
can reduce the database size by periodically extracting archived data.
After the data is archived, you can remove a specific range of archive data permanently from your
system. Exporting and deleting of old archive data is to be carried out to align with your data
retention and records management life cycle policies.
Warning
Do not perform the export operation during peak hours or while doing upgrades. After you
start the export operation, you cannot cancel it.
Archive data management operations

You can perform any one of the following archive operations:
Export and Delete — exports and deletes data in the archive forms
Export — only exports the data in the archive forms
Delete — only deletes data in the archive forms
To export and delete archive data
1. Log on to the mid tier.

2. Access the AR System Archived Data Management form by typing the URL in the given
format:
http://<serverName>:<portNumber>/arsys/forms/<serverName>
/AR+System+Archived+Data+Management
3.
3. In the Archived Data Management dialog box, click New request.

4. From the Operation drop-down, select Export and Delete.
5. In the Age in Days field, enter the age of the archive.
6. Ensure that the CSV export format is selected.
7. Click Save.
8. Click New search to search for the record that you was exported.
9. Enter the age of the archive as the search criteria.
10. Click Search.
11. The Status field displays the status of the operation.
12. Upon completion of the operation, the Result field displays the result of this operation,
which is a directory containing the exported archive having the
<AGGAA5V0HGXU0ANJECBEAAAFI4HFYR> format. If the operation failed, the Result
field displays an error message with information about why it failed. You can see detailed
error logs in the arextension.log file located in the <ARInstallationDirectory>/ARServer
/Db directory.
Result of the archive Export and Delete operation
Notes
You can export/delete all the archived forms present in the system. For each
exported archive form, a new CSV file is created in a directory located under the
<ARInstallationDirectory>/ARServer/Db directory.
Errors, if any, are logged in the arextension.log file located in the
<ARInstallationDirectory>/ARServer/Db directory.
Exporting and deleting archive data is an asynchronous operation. When you
create an entry in the system form, AR System Archived Data Management,
workflow defined on this form runs in the background.
In a server group environment, the export and delete operation runs on the server
on which the entry was created. However, if the mid tier is connected to a load
balancer, then create entry operation could be sent to any of the servers in the
group that are behind the load balancer. If you need the export and delete
operation to run on a specific server in the group, then you must specify the server
before you create entry into AR System Archived Data Management form.

You can also perform a export and delete operation from the Archiving console,
which provides a more wizard-like experience. For information about using the
Archiving console, see Managing the archiving process (see page 1911).
Limitation
Only CSV format is supported for exporting.
Deleting an archive form

You can delete an archive form by using BMC Remedy Developer Studio or by using an API call.
When an archive form is deleted, archive settings are cleared for the main form. The Archive Type
field is reset to None in the Archive page of the Form Properties dialog box.
To delete an archive form using BMC Remedy Developer Studio
1. Make sure that the main form in BMC Remedy Developer Studio is closed.
If the main form is not closed, your archive form might be regenerated and the archive
settings might not be cleared.
2. In BMC Remedy AR System Navigator, expand serverName > All Objects.
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. 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

AR System server updates the archive form:
Attributes
Entry mode
Field limits
Help text
When you modify the following properties, the archive form is unchanged:
Display properties
Index for FTS
Permissions
Fields on archive forms are always read-only.

Deleting archive fields from the main form

When you delete multiple fields from the main form, the BMC Remedy AR System server attempts
to delete those fields from the archive form. If any of those fields contains data, none of them are
deleted from the archive form.
However, if the fields are deleted one by one from the main form, the fields that do not contain data
are deleted from the archive form.
Characteristics of archive forms

In this topic:
All archive forms (see page 1909)

Archive forms created by BMC Remedy AR System (see page 1910)
Distributed Server Option (DSO) and archive forms (see page 1910)
All archive forms

All archive forms have the following characteristics.
General
The archive form is a regular form. The detail view in the BMC Remedy Developer Studio
forms list shows its Type as Archive.
Changes to the definitions of the main form (for example, adding or deleting FTS or
database indexes) are also applied to the archive form. Addition of data fields cause the
same fields to be created on the archive form. Deleted data fields are deleted from the
archive form if the form contains no data; otherwise they are preserved.
Trim and button fields are not created automatically, but you can manually add trim and
button fields to an archive form.
View changes are not part of the form definition and changes to them are not applied to the
archive form. You can change the form and view properties of the archive form explicitly.
If the main form belongs to a deployable application, the archive form also belongs to the
same application.
If the main form is made "licensable", the archive form is also made licensable.
The archive form cannot be audited or further archived.
Fields
When the BMC Remedy AR System creates a new archive form, the following two fields are
included on the form:
Original Request ID (ID 450)
Original Create Date (ID 451)
These fields contain the Request ID and Create Date from the main form. These
fields are not placed in the view. To add them, open the archive form in BMC
Remedy Developer Studio, and choose Form > Add/Remove Fields On View.

Then, move the fields to the Fields in View table.

You can use the Create Date of the archive form as the archive date. The remaining
core fields on the archive form contain the same values as the main form.
Data fields, attachment pools, and panel holder cannot be modified or added to an archive
form. All other field types, such as trim or table, can be added or modified.
The data fields in the main and archive form have identical field limits. The permissions on
archive forms are always read access.
Workflow
Workflow from the main form is not attached to the archive form when it is created. You can
add workflow to an archive form, but workflow cannot modify data in an archive form.
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 (see page 1909):
Any unique index on the main form is created as a non-unique index on the archive form. As
the Entry ID and Create Date fields are duplicated on the archive form in the new fields,
any index on those fields is applied to the new fields instead.
When an archive form is created, the entry points are cleared, but you can add entry points.
All other form properties are copied from the main form to the archive form. However, after
the archive form is created, subsequent changes to the main form properties are not copied
to the archive form.
The owner of the non-core fields on the archive form is set to the owner of the archive form,
not the original form.
Distributed Server Option (DSO) and archive forms

When a form used in a distributed operation is archived, the distributed fields are copied to the
archive form but are not updated. You cannot add distributed fields to an archive form.

Changes to the definitions of the main form (for example, adding or deleting FTS or database
indexes) are also applied to the archive form.
· Addition of data fields cause the same fields to be created on the archive form. Deleted data
fields are deleted from the archive form if the form contains no data; otherwise they are preserved.
Managing the archiving process

The AR System Archive Manager console is where you manage the archiving process. You can
perform the following tasks from the Archive Manager console:
Task Description
AR System Archive Manager Walkthrough of the BMC Remedy AR System Archive Manager console and managing the
console overview archiving solution. Click here to learn more.
Opening the AR System Archive Steps to launch the console. Click here (see page 1911) to learn more.
Manager console
Turning archiving on and off Enable or disable archiving. Click here to learn more.
Changing how often the archiving Control the frequency of archiving. Click here to learn more.
process runs
Changing when a record is ready Determine whether a record is ready for archiving. Click here to learn more.
for archiving
Disabling individual archiving Disable archiving of specific record types. Click here to learn more.
policies
Running an on-demand archive Run archiving outside the archiving schedule. Click here to learn more.
process
Exporting and deleting archive Move or delete archived records. Click here to learn more.
data
Stopping an archive run after it Stop an on-going archiving operation. Click here (see page 1911) to learn more.
has started
Opening the AR System Archive Manager Console
1. In a browser, go to the following URL address: http://<hostName>:<portNumber>

/arsys/
2. Log on.
3. Select AR System Administration > AR System Archive Manager Console.
Stopping an archive run after it has started

If you need to stop the archive run after it has started, there are a couple of ways to do that,
depending on the type of archiving run you need to stop:

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 (see page ).
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 (see page 2085).
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.

Integrating and migrating data

BMC Remedy Action Request System (BMC Remedy AR System) provides data management
services to enable the following:
Integration of external data with data residing in your BMC solution stack
Data migration, import, change, and export
Data integration
The Atrium data integration services are available for BMC Remedy AR System through the Atrium
Integrator adapter, an AR System Database Connectivity (ARDBC) plugin, the Atrium Integrator
Spoon client, and the Atrium Integrator engine forms — all are installed with the AR System server.
These services enable you to:
Gather, or extract, data from a variety of sources

Change and transport, or transform, data
Store, or load, data in one or more target locations
You can rapidly extend the scope of your data management capabilities by adding Atrium
Integrator, the BMC Remedy ITSM suite of applications, and the BMC Atrium Configuration
Management Database (CMDB).
The following diagram illustrates the AR System interaction with the Atrium Integrator adapter, the
Spoon client, and the Atrium Integrator engine forms.
Atrium Integrator adapter and related components

Atrium An ARDBC plugin that receives requests for executing and monitoring jobs from the AR System server, sends
Integrator them to the Atrium Integrator Carte server, then returns the Carte server results to the AR System
adapter server. Installed with your AR System server.
Atrium A GUI used to create and manage data integration jobs and transformations. Installed with your AR System
Integrator server.
Spoon client
(see page 1968
)
Atrium A web server for data integration that allows remote job and transformation execution by accepting XML files
Integrator that contain the job's (or transformation's) execution configuration. Enables remote monitoring as well as starting
Carte server and stopping of jobs and 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
Integrator AR server and/or the BMC Atrium CMDB. Installed with your AR System server and BMC Atrium Core installation.
and CMDB
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
AR System repository.
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
Integrator Carte server. Installed with your AR System server.
engine forms
(see page 1945
)
External data Flat files, spreadsheet files, database files, or other data that is imported or exported to or from your AR System
server for data migration.
AR System permissions scheme

Access to the Spoon client application and all base vendor forms for the ARDBC plug-in is
configured in the BMC Remedy AR System permissions interface. To use the Spoon client you
must connect to an Atrium Integrator repository, which resides on the AR System server. The
Spoon client requires an BMC Remedy AR System user with administrator permissions to connect.
To access the base vendor forms of the ARDBC plug-in, the user's role must be either an AR
System UDM administrator or an AR System UDM user.
Related topics
Atrium Integrator
Importing data with Atrium Integrator in BMC Atrium Core 9.0 online documentation.

Configuring Atrium Integrator for data import in BMC Atrium Core 9.0 online
documentation.
Troubleshooting in BMC Atrium Core 9.0 online documentation.
Known Issues in BMC Atrium Core 9.0 online documentation.
BMC Remedy ITSM
Data Management in BMC Remedy IT Service Management Suite 9.0 online

documentation.
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
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 (see page 1920).
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 (see page 1924).

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 (see page 1929).
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 (see page 1965).
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

Data type Description
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 Atrium Integrator Adapter Data

Type Type
Null None
Integer Integer
Real Number
Char String
Diary String
Time Integer
Bitmask Integer
Bytes Binary
Decimal Bignumber
Attach Binary
Date Date
Time of Day Integer
Ulong Integer
Display String
View String
Complex AR System data types such as Attachment, Currency, and Status History are handled in
the same way the AR System Import tool and ODBC driver handle data types. For example, the
Currency field is split into its separate parts, such as Date, Type and Value, and each is identified
separately in the field list. See Importing data into BMC Remedy AR System forms (see page 1969)
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 AR System Data

Type Type
None Null
Number Real
String Char

Atrium Integrator Adapter Data AR System Data

Type Type
Date Date
Boolean Enum
Integer Ulong
Bignumber Decimal
Binary Attach
ARX File Input step

The ARXInput step allows you to read data from ARX files and import them into BMC Remedy AR
System forms (or any other output data source.)
Passes an ARX file to the AR System ARX parser which extracts schema info and data
lines.
Displays schema names in a list, which allows the user to select one schema at time.
Displays all fields for the selected schema in the Fields table when the Get Field button is
clicked.
During an execution of a transformation, the ARX parser reads the data line and converts it
into a token.
Converts tokens into the proper Atrium Integrator data types.
Handles multiple schemas in single file.
Treats multiple occurrences of same schemas as single schema and combines all data
together.
The data type conversion is same as that of the ARInput step, see ARInput data type conversions
(see page 1923) 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

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

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.
4. Restart the AR System server.
Example
<logger name="com.bmc.arsys.pdi">
<level value="info" />
</logger>
AR System form log files
The Log field in the UDM:ExecutionStatus form shows the log file for a specific Execution
Instance. However, the log lines displayed are stored in the Carte server's memory, which has a
maximum buffer of 5000 lines to control memory usage. As new log file lines are added, the Carte
server deletes the older log file lines. However, this information is retained in the arcarte.log with
all other Carte server log file information. See the third-party documentation for more information
about this logging limitation.
To configure the Carte server to store more than 5000 log lines, set the
KETTLE_MAX_LOG_SIZE_IN_LINES parameter in the armonitor.cfg file for the Carte Java
process, and restart the AR System server.

A transformation or job can be configured to log the execution information to AR System logging
forms. Use these forms to configure logging:
UDM:TransformationLog — Stores transformation instance log.

UDM:JobLog — Stores job instance log.
UDM:JobEntryLog – Stores job entries log for a specific job instance.
UDM:StepLog — Stores steps log for a specific transformation instance.
To enable form-level logging for a transformation or job:
1. Open the transformation or job in the Spoon client.

2. Right-click on the transformation or job name.
3. Click the Logging tab.
4. Add the AR Server connection and the corresponding AR form name for the log table name.
For example, use UDM:TransformationLog for the transformation and UDM:StepLog for the
step.
5. Save the transformation or job.
Spoon client log files
When you run a transformation or job in the Spoon client, the log information is displayed in the
Logging tab of the Execution results panel.
Spoon client log information


Error message descriptions
This section describes runtime, design, and plug-in error messages for the Atrium Integrator
adapter. For related BMC Remedy AR System error messages, see BMC Remedy AR System
error messages (see page 4448).
Runtime error messages
Message Description
You need to specify a A connection to AR system is missing from a transformation step.

BMC Remedy 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 An ARInput or AROutput step in your transformation cannot connect to BMC Remedy AR System.
ARSystem.
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 The ARInput step failed to parse the specified qualification.
qualification
Error while fetching The ARInput step failed to fetch the string enum values for the Status field (AR Core field ID 7).
status field enum
values
Error while fetching The ARInput step failed to fetch the next chunk of records from the AR System server.
next set of records
Error while converting The ARInput step failed to convert the BMC Remedy AR System data type value to an Atrium
AR value to Pentaho Integrator value.
value
Ensure that the source and target data types are compatible.
Error while fetching The ARInput step failed to fetch the Status History field value for a row.
status history
Error while fetching The ARInput step failed to fetch the Attachment value for a row.
attachment for field: {0}
Field {0} couldn't be The AROutput step cannot find an AR System field contained in the field mapping.
found on form {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 The AROutput step cannot locate the stream field (fields from previous steps) and defined in the field
found in the input mapping.
stream!
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 The AROutput step failed to commit the bulk entry transaction.
Transaction: {0}
More than one entry Review the qualification and modify it to ensure that it matches one entry, or change the multi-match
matched the option to update first or update all.
qualification and the
multi match option is
set to ERROR
Error while parsing The AROutput step failed to parse the specified matching qualification.
matching qualification
No or Empty Currency The AROutput step cannot find the currency code for the currency field value.
Code for Currency
value for field {0} Map the currency code (<currency field name>.TYPE) in the field mapping, or ensure that the
stream field (mapped to the currency field) defines the currency code value.
No conversion date for The AROutput step cannot find the conversion date for the currency field value.
Currency 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 The AROutput step cannot find the decimal value for the currency field.
field {0}
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 A currency conversion between two different currency types was needed during the execution of a
Conversion Ratio transformation that included the AROutput step. The conversion ratio was not defined in the AR
Defined from {0} to {1} System Currency Ratios form.
Supply conversion ratios in the AR System Currency Ratios form for all possible conversions.
Error while fetching The AROutput step failed to fetch field information from a form in BMC Remedy AR System.
fields information for
form {0}
EXTERNAL operator is Remove the External operator from the qualification.

not supported in the
matching qualification
No such form field The AROutput step cannot find the Field ID used in the matching qualification on the form.
having field ID {0}
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 The AROutput step determined that stream fields (fields from previous steps) are used in the left side
Qualification. Stream of the relation operation in the matching qualification.
field {0} should be used
on the right hand side Modify the matching qualification to use stream fields on the right side of the relation operation in the
of a relational matching qualification. Use the Spoon client to access the qualification editor provided in the AROutput
operation. step dialog, and configure the qualification. Press the Configure Matching Qualification button on
the Duplicates tab to access the qualification editor.
No such stream field

[{0}]

The AROutput step cannot find a stream field (field from the previous step) referenced in a matching
qualification.
Review the qualification to remove the non-existing stream field references. Use the Spoon client to
access the qualification editor provided in the AROutput step dialog, and configure the qualification.
Press the Configure Matching Qualification button on the Duplicates tab to access the qualification
editor.
Error initializing step... The file path specified in the ARX File Input step or specified as a variable value is not found on the
java.io. system.
FileNotFoundException:
Ensure that the file is present on the system.
Error while setting the An error occurred while setting the private RPC queue number on the AR connection.
private RPC Queue
Error while reloading An error occurred while reloading information from the UDM:RAppPassword form.
the password collection
Did not find Remedy The Remedy Application Service password for a server is missing from the UDM:RAppPassword form.
Application Service
password for server {0} Add an entry for the server in this form.
in UDM:RAppPassword
Form on server {1}
Error while An error occurred while impersonating the provided user.

impersonating user {0}
Error occurred while An error occurred while starting a client managed transaction on the AR connection.
trying to create
transaction on the
ARdatabase
No valid database No connection related information is defined on AR connection. Please define host, port, TCP
connection defined! port, RPC port, user name on connection to avoid this error.
Error occurred while An error occurred while connecting to BMC Remedy AR System.
trying to connect to the
database
Error disconnecting An error occurred while disconnecting from BMC Remedy AR System.
ARdatabase: {0}
Error performing An error occurred while committing the client managed transaction on the AR connection.
commit on connection
Error performing An error occurred while rolling back the client managed transaction on the AR connection.
rollback on connection
Error occurred while An error occurred while fetching a list of form names from BMC Remedy AR System.
trying to get list of
tables
Error occurred while An error occurred while fetching a list of fields on a form from BMC Remedy AR System.
trying to get table fields
Error occured while An error occurred while fetching form entries from BMC Remedy AR System.
trying to get table
entries

Error while converting An error occurred while converting an AR data type value to an Atrium Integrator value.
AR value to pentaho
value Ensure that the source and target data types are compatible.
Error while fetching last An error occurred while fetching the last log date from log forms such as, the UDM:TransformationLog
log date form or the UDM:JobLog form.
Unable to write log An error occurred while writing a log record to the logging form, such as the UDM:TransformationLog
record to log form {0} form or the UDM:JobLog form.
Error while fetching log An error occurred while fetching log records from logging form such as, the UDM:TransformationLog
records from {0} form form or the UDM:JobLog form.
Error while clearing log An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog
form entries from {0} form or the UDM:JobLog form.
form
A log timeout was A log timeout value is defined in the logging setting, but the log date field is not defined on the log form.
defined for log table {0},
but it doesn't have a log Ensure that you are using out-of-the box logging forms such as, the UDM:TransformationLog form or
field 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 An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog
log records from log form or the UDM:JobLog form.
table {0}
Invalid selection value The AROutput step found that the provided string value is not a valid string alias selection value for the
{0} for field [Name - {1}, enum field.
ID - {2}]
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 The AROutput step cannot convert a string value to a diary list field value.
converting string to
diary list value1
Java.lang. If this error message appears in transformation and/or job execution logs or in the arcarte.log file, the
OutofMemoryError 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 The AR System connection is not configured for an ARInput or AROutput step.
select a valid
connection! Configure a new connection, or select existing connections for an ARInput or AROutput step using the New and
Edit buttons on the General tab of the ARInput or AROutput step dialog.
Please The Form name is not configured for the ARInput or AROutput step.
select a 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.
Configure fields in the ARInput step.
Use the Get Fields button on the Fields tab in the ARInput step dialog to see all the form fields from the .arx file.
Delete or add fields as needed.

No fields are
specified.
Please add
fields in
fields tab.
Field with A Field name specified on Fields tab was not found on the ARInput step form.
name {0}
does not Make sure you entered the correct Field name on the Fields tab. Use the Get Fields button on the Fields tab in
exist on form the ARInput step dialog to see all form fields. Delete or add fields as needed.
{1}
Invalid field A Field ID specified on Fields tab is non-numeric for the ARInput step.
ID {0}. Field
ID should be Ensure that the correct Field ID was entered on the Fields tab. To avoid this error, use the Get Fields button on
a number. the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.
Field with ID A Field ID specified on Fields tab is not found on the ARInput step form.
{0} does not
exist on form Ensure that you entered the correct Field ID in the Fields tab in the ARInput step dialog. Use the Get Fields
{1} button on the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.
Field with ID The Field Name for a Field ID is different than the actual Field name of the Field ID in the form definition.
{0} does not
have name Ensure that you entered the correct Field Name in the Fields tab in the ARInput step dialog. It must be in sync
{1} on form with the form definition fields in your BMC Remedy AR System server. Use the Get Fields button on the Fields
{2} 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 Configure the field mappings with the AROutput step field mapping editor. To access the editor, press the Edit
specified. Mapping button on Field Mapping tab of AR output step dialog.
Please
specify field
mappings in
field
mapping tab.
It was not The AROutput step dialog cannot retrieve any stream fields (fields from previous steps).
possible to
retrieve the If the AROutput step is not connected to a previous step, create a hop between the previous step and
source fields the AROutput step.
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
possible to Remedy AR 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 Check if the hop between the previous step and the AROutput step is disabled. If it is disabled, enable the hop
not found! and save the transformation. Also check if a field was removed from previous step but not removed from the
These AROutput step field mapping. If it was removed, remove it from the field mapping and save the transformation. In

source fields addition, check if the field is defined as an error handling parameter in a previous step. If the hop between the
were not previous step and the AROutput step is not defined as a normal hop or as an error hop, change the hop type from
found: {0} 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
referenced mapping to ensure that the correct field names are used.
fields were
not found!
These target
fields were
not found:
{0}
An ARX file The ARX file path is not configured for the ARX File Input step.
is not
specified. In the Spoon client, add the ARX file path using the Browse button on the ARX File Input step dialog, or specify
You must the value as a variable and supply the variable value at execution time.
specify the
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.
fields in Delete or add fields as needed.
fields 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 The ARDBC plug-in failed to fetch the requests left to process since the last processing.
requests
Carte Server Name is not populated In a server group environment, the Atrium Integrator Engine Server Name field is not
in UDM:Config for entry ID {0} populated with an Entry ID from the UDM:Config form.
Enter a value in the Entry ID field, and enter the co-located AR System server's name
(Server-Connect-Name) in the Atrium Integrator Engine Server Name field. Using the
value in this field, the Atrium Integrator adpater ARDBC plug-in will send the Carte server
the request.

Did not find Remedy Application A BMC Remedy AR System server's Remedy Application Service password is missing
Service password for server {0} in from the 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 The Atrium Integrator adapter ARDBC plug-in only supports the Create Entry call in the
{0} UDM:Import form, the UDM:Execution form, and the UDM:ScheduleProcessor form.
Error while creating an entry on form A Create Entry operation failed in an Atrium Integrator adapter ARDBC plug-in vendor
{0} form.
There was an error removing the The Atrium Integrator adapter ARDBC plug-in failed to remove an Execution Instance of
execution instance {0} of a transformation or job 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 doing pause The Atrium Integrator adapter ARDBC plug-in failed to pause or resume an Execution
/resume for execution instance {0} of Instance of a transformation from the Carte server.
transformation/job {1} on the Carte
about this error.
There was an error stopping the The Atrium Integrator adapter ARDBC plug-in failed to stop an Execution Instance of a
execution instance {0} of transformation or job from the Carte server.
about this error.
There was an error starting the The Atrium Integrator adapter ARDBC plug-in failed to start an Execution Instance of a
execution instance {0} of transformation or job from the Carte server.
about this error.
Repository Directory or Object ID is For the Create Execution Instance request, you must provide a Repository Directory or
required for Operation an Object ID 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 transformation or job on the Carte server.
server {0}: {message}
Review the Carte server error message and the arcarte.log file for more information
about this error.
Failed to reload password collection The Atrium Integrator adapter ARDBC plug-in failed to re-read all the passwords from
UDM:RAppPassword form.
Get List Entry With Fields not The Atrium Integrator adapter ARDBC plug-in only supports a Search entry with a Get
supported on form {0} List Entry With Fields API call only on the UDM:RepositoryObject form, UDM:
ExecutionStatus form, and the UDM:StepStatus form.
Error while fetching data from form A Search Entry operation failed on a vendor form that belongs to the Atrium Integrator
adapter ARDBC plug-in.
Qualifier operator OR and NOT are In the vendor forms that support Search, modify your qualification because only the AND
not supported only AND is supported conditional 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
supported for qualifier EQUAL relational 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
Supported fields for query are {1} qualification because an unsupported field is used in the qualification.
No such repository directory {0} The existing directory name is not valid for the Execution Instance operation on the UDM:
Execution form or the Search operation on the UDM:RepositoryObject form.
Provide the correct repository directory name on the UDM:Execution form or the UDM:
RepositoryObject form.
Delete Entry not supported on form A Delete Entry API call is not supported on any vendor form that belongs to the
{0} 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 A Search Entry operation fails on a vendor form that belongs to the Atrium Integrator
{0} adapter ARDBC plug-in.
No Carte server with name {0} exists A transformation or job uses the UDM:PermissionInfo form, which specifies a Carte
in UDM:Config form. server name, but the UDM:Config form does not contain an entry for that Carte server
name. Use the correct Carte server name and use the menu in the Atrium Integrator
Engine Server Name field on the UDM:PermissionInfo form.
Execution instance name {0} is not The Execution Instance name provided for the Create Execution Instance operation is
unique for transformation/job {1} not unique.
Provide a unique Execution Instance name.
Invalid Execution Instance. Execution The Execution Instance name provided for the Start, Stop, Pause, Resume or Remove
Instance {0} does not exist or user {1} operation does not exist in the database.
is not 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} The transformation or job provided for the Create Execution Instance operation does not
(Object ID {1}, Directory ID {2}) does exist.
not exist Or User {2} is not allowed to
access transformation/job {3} Provide the correct transformation or job name and directory or object ID. If the
transformation or job exists, then the user does not have permission for the
transformation or job. To add permissions, update Field 112 in the transformation or the
job's record on the UDM:PermissionInfo form.
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 The ARDBC plug-in failed to process an asynchronous UDM:Import task.
ID {0})
Invalid xml file. Root Element should

be transformation or job

The transformation or job definition file attached to the UDM:Import record is not a valid
file.
Attach a valid transformation definition (.ktr) or job definition (.kjb) file to the UDM:Import
form.
Transformation/Job {0} already exists The transformation or job being imported exists in a repository directory.
in repository directory {1}
Use Overwrite mode to overwrite the existing definition.
No Pentaho repository and Carte The UDM:Config form is empty.

server 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.
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 UDM Admin role UDM User role

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

Form name Form UDM Admin role UDM User role

type access access
UDM:RAppPassword Regular x
UDM:RepositoryObject Vendor x x
UDM:ScheduleProcessor Vendor x
UDM:StepLog Regular x x
UDM: Regular x x
StepPerformanceLog
UDM:StepStatus Vendor x x
UDM:TransformationLog Regular x x
UDM:Variable Regular x x
UDM:CartePending 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 (see page 1949)

Variable form (see page 1965)

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.
Carte pending form

The UDM:CartePending form provides information of all the new and in-progress jobs running on
Carte servers. This form is used internally to fail-over new and in-progress jobs.
UDM:CartePending form
Use these fields to see the details of new and in-progress jobs:
Name: Enter specific job or transformation.
Type: The type of the repository object such as a job or a transformation.
Directory: The repository directory in which the transformation or job is stored
Atrium Integrator Engine Object ID: Internal unique identifier assigned by the Atrium Integrator
engine for the execution instance.
Object ID: Unique identifier for the repository object
Atrium Integrator Engine Server Name: The name of the server hosting the Carte server.
Job-Transformation Status: Choose to view jobs with status New and In Progress
Job Configuration XML: Lists the details of all the New or In progress jobs depending on the
selection.

Atrium Integrator Spoon client

The Atrium Integrator Spoon is a client side, user installable graphical user interface application
which is used to design transformations and jobs. These transformations and jobs are saved, and
then accessed and executed by the Atrium Integrator adapter for BMC Remedy AR System. The
Spoon client also allows you to define and create the AR Connection modules which enable the
transformations to use AR Systerm database transactions.
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 in BMC
Remedy ITSM Deployment online documentation.
Once installed, the application can be accessed from the Windows Start menu, under Programs,
under the BMC Software folder. AR System administrator permissions are required to log on and
use the Spoon client.
Scheduling and manually executing a transformation or job

Atrium Integrator uses workflow-based forms and scheduling operations in AR System to schedule
transformations or jobs for execution.
To schedule a transformation or job
1. Create an execution instance on the AR System server using the UDM:Execution form.
2. Select Create Execution Instance in the Operation field.
3. Create an entry in the AR System Job form and include the date, time, and recurrence.
4. Create an entry in the AR System Job Item form with the Atrium Integrator transformation or
job name and execution instance name created in step 1.
When a job is executed in this framework, an entry is automatically added to the UDM:
ScheduleProcessor form. This form then processes the job based on the job parameters.
The scheduling framework provides a escalation that runs hourly and retrieves due jobs from AR
System Job form. The due jobs are moved to a pending queue where the pending queue
processor writes each job item entry to appropriate vendor form based on a job type mapping
provided in the AR System Job Type Mapping section.
For the "pentaho" job type, AR System places an entry into the UDM:ScheduleProcessor vendor
form. The ARDBC plug-in form receives all the parameters, such as the transformation or job
name, type and execution instance. Then it starts the execution instance on the Atrium Integration
engine server using these parameters.

To manually execute a transformation or job
1. Create an execution instance on the AR System server using the UDM:Execution form.
2. Select Create Execution Instance in the Operation field.
3. Assign the other fields on the form as necessary.
4. Use the UDM:Execution form to create another entry.
5. Select Start Execution Instance in the Operation field. (You can also stop, pause/resume,
or remove an execution instance by configuring another value in the Operation field.)
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 (see page 1969)
The import process (see page 1970)
Supported mapping file types (see page 1971)
Defining Data Import preferences (see page 1972)
Creating mapping files (see page 1976)
Importing data (see page 1979)
Using a saved mapping file (see page 1980)
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 (see page 1970)
To start Data Import and log in to AR System servers
1. Select 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 situations, this field is not used. See Setting up an authentication
alias (see page 1328).
You can also configure an External Authentication (AREA) plug-in. See Configuring
the AREA LDAP plug-in (see page 799) and AREA plug-in API functions (see page
751).
b.
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 (see page ).
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 (see page 1970) through 9 (see page 1970) for each server Data Import must
connect to.
12. Click OK.
13. In the Login dialog box, click Login.
Changing the current login

To log in to a different server or as a different user, you must change your login.
To change the current login
1. Select File > Relogin.

2. In the Login dialog box, change the server list, user name, password, and other information
as described in To start Data Import and log in to AR System servers (see page 1969).
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
(see page ).

For information about exporting and importing object definitions, see Importing and exporting
object definitions and locking objects (see page 3401).
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 (see page ).)
3. Define Data Import preferences. (See Defining Data Import preferences (see page ).)
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 (see page ).)
7. Import the file. (See Importing data (see page ).)
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 (see page 3664).
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 (see
page 3191).
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
Records value of 100, the server performs only one commit to the database every 100 records, which
Per significantly improves performance.
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,
IDs By whether or not any IDs are duplicates. Generates request IDs for records that do not already
have them, for example, in a CSV file created outside AR System.
Reject Duplicate Records — Entries are imported using their existing IDs. If an ID is already
in use, an error is generated. The error is processed according to your preferences. See
Defining Data Import preferences (see page 1972) 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 (see page ) 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 (see page 1974) 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 Non- Specifies that noncore required fields are optional during the import. By default, the check box is
Handling Core cleared, and all required fields are treated as required. If a required field has a NULL value, an error
Required is generated. The error is processed according to what you enter in the Bad Records field under the
Fields "Error Handling" section.
Optional *
Disable Specifies that records are imported, even if the data in a field does not match the specified pattern.
Pattern By default, the check box is cleared, and the server rejects records if data in the field does not match
Matching * the specified pattern. The error is 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
Field importing for the field is 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
Leading is cleared, and values are imported exactly as they appear in the data file.
Spaces
and Tabs *
Specifies that all trailing white space is removed from each field imported. By default, the check box
is cleared, and values are imported exactly as they appear in the data file.

Remove
Trailing
Spaces
and Tabs *
Truncate Specifies that fields that are too long are truncated. By default, the check box is cleared, and fields
Strings whose contents are too long generate an error. The error is processed according to what you enter in
Exceeding the Bad Records field under the "Error Handling" section.
Field Limit
*
Import Specifies how BMC Remedy AR System imports records that contain fewer fields than described by
Records the field titles in the data file. Problem records are imported with NULL values in the missing fields.
with Too By default, the check box is cleared, and the problem records are not imported and an error is
Few Fields generated. The error is processed according to what you enter in 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
Records the field titles in the data file. By default, this option is selected. The problem records are imported,
with Too and the extra fields are ignored. If you clear the check box, the problem records are not imported,
Many and an error is generated. The error is processed according to what you enter in the Bad Records
Fields 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
Separator use any character that is not part of the field separator string for the data file.
Long Date Defines the long-date format. The options are

Format
dddd, MMMM d, yyyy
dddd, d MMMM, yyyy
dddd, yyyy MMMM d
The component order is based on the Locale settings as defined by Java.
Time 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
(Time default. You can use any 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 Defines the separator for groups of real numbers in .arm and .armx files.
Number Group
Handling Separator
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
(see page 114) and Creating and managing fields (see page 2565).
Creating mapping files

Creating a mapping file (see page 1977)

Tips for mapping all data file fields (see page 1979)
A mapping file determines which pieces of data to import into the fields on the target form
(mapping) during the import process. You can map all fields in a data file to all fields in a form, or
you can map fields individually.
How data fields are matched to form fields

Data Import matches data fields to form fields as follows:
AR Export or AR XML — Field IDs are matched first, and then field names are matched for
fields without matching IDs.
CSV or ASCII — Only field names are matched.
Defining default mappings

You can define fallback mappings, which are default mappings that direct the Data Import
response if a data mapping problem occurs during an import. Fallback mappings are used when
the data value is invalid for the destination form field type. For example, if a problem occurs while a
value is mapped, the fallback mapping for the field is used if one is defined. If no fallback mapping

exists, an error is generated. If a fallback mapping fails, errors are generated on the original failed
mapping, not the fallback mapping.
When only the AR System server can detect the error (such as when the data is not an acceptable
value), the fallback mapping is not used. For example, the data value is outside the range set for
the form field, or a required field has a NULL value.
To create a mapping file
1. Log in to Data Import.

2. Choose File > New Mapping.
3. In the Mapping File Editor, complete the following fields in the Data File and Server section:
New Mapping dialog box fields
Field Description
Source Export file that contains the data to import. The file must be in .arx, .csv, .xml, or .asc format.
Data File
Contains (CSV and ASCII format only) Determines whether BMC Remedy Import converts the field titles into data.
Field If the first line of data contains field titles, select the File Contains Field Titles check box so that the
Titles 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
Options used, and other 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 (see page ).
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.

d.
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 (see page 2788).
e. Repeat this step for all the fields that you want to map.
Note
If the data file contains duplicate field titles, an error is generated. If the data
is*.arx* or .xml format, the field titles appears as their field IDs. If the data
file is .csv or .asc format, the fields appear with an appended number (for
example, fieldTitle1, fieldTitle2, and so on).
5. (Optional) Define fallback mappings for fields.

For more information, see Defining default mappings (see page 1976).
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 preferences (see page )for a description of most of the
options. The differences are
The Options tab does not include a Log File field, but it is included in the Preferences
window.
The Options tab includes the following fields, which are not included in the
Preferences window.
Additional Data Handling field on the Options tab

Group Field Function

name
Data Disable Setting this flag causes the server to suspend enforcement of associations on
Handling Enforced entries getting imported. Associations are still enforced on other entries affected by
Associations workflow that might be triggered by entries getting imported. The server will only
honor this flag if the user of the import tool is an administrator.
8. (
Optional) Save the mapping.
9. Import the data as described in Importing data (see page ).
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 (see page ).
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.
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 (see page 3404).
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 (see page 4657).

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 (see page 2257).)
The DefinitionImport.bat and DefinitionExport.bat command-line utilities (See
Enabling the import-export command-line utility. (see page ))
The C and Java APIs (See Developing an API program. (see page 3533))
To export data, use the command-line utility described below:
The runmacro command-line utility (See Enabling the runmacro command-line utility
(see page ).)
To import data, use the command-line utility described below:
The Data Import command-line utility (See Enabling the Data Import utility. (see page
))
This section describes the command line interfaces for importing and exporting data
and definitions.
Exporting objects and data to XML format (see page 1981)

Enabling the import-export command-line utility (see page 1982)
Enabling the runmacro command-line utility (see page 1986)
Enabling the Data Import utility (see page 1988)
Exporting data by using the AR Export command-line utility (see page 2003)
Exporting objects and data to XML format

In this topic:
Exporting BMC Remedy AR System objects in XML (see page 1981)

Exporting BMC Remedy AR System data in XML (see page 1982)
Using XML with the BMC Remedy AR System API (see page 1982)
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 (see page 3533).
Enabling the import-export command-line utility

This section contains information about using the import/export command-line utility to import and
export definitions.
Import-export utility guidelines (see page 1983)

DefinitionImport and DefinitionExport options (see page 1983)

Import-export scenarios (see page 1985)
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 (see page ).
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 (see page ). Options are interpreted in a
predictable order and might not be executed in the order you enter them.
You cannot perform an action against two servers with one command. For example, you
must issue two commands to export object definitions from one server and import them into
another server.
Enclose arguments that contain blank spaces or symbols in quotation marks.
DefinitionImport and DefinitionExport options

The options in the following table are optional unless the description states they are required.
Options that can be repeated are marked in the Repeat column.
Option Parameter Description Repeat
-- Writes the version to standard output and exits without executing other options.
version
-u userName Uses the account to connect to the server. Required.
-p password Uses the password to connect to the server. Required if the account has a
password.
-x server Connects to the server to import or export. Required.

-w authentication Uses external authentication string or Windows domain to connect to the server.
- portNumber Uses the TCP port number to connect to the server. Required if the server does not
portnum 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

Option Description
Home directory — Path to the ARSystemHomeDir directory. If you do not specify the -d option, runmacro also looks
in this directory for the arcmds directory that contains the macro to run.
-d Macro directory — Directory that contains the macro if your macro is not in the ARSystemHomeDir\arcmds directory
or if you do not have an ARSystemHomeDir directory.
-x Server name — Name of a server to connect to. This option might be included more than once to connect to multiple
servers. Use the following format: -x serverName
-e (or Macro name — Specifies the macro to run.

-i )
-p Parameter — Value for a parameter. There might be more than one -p option in a command line. If the macro specified
(using the -e or -i options) has a parameter, a value can be supplied by naming that parameter and assigning a value.
If the parameter name or value includes a space or other special character, the data must be enclosed in quotation
marks to cause proper interpretation of the special characters. Use the following format for each parameter specified: -p
parameter = value
-U User name — Required login parameter that identifies the user account. The -U option must be in uppercase.
-P Password — Optional login parameter that identifies the user account. Omit the -P if the user account has no
password. The -P option must be in uppercase.
-Q Internal qualification format — Query in AR System internal format.
-q Client tool qualification format — this is a regular query.
Within the query string, double quotation marks must be preceded by a backslash (), which functions as an escape
character. For example:
runmacro.exe -o <outputFileName>-x <serverName>

-U <userName> -P <password> -f <form> -t {arx|csv|xml}
-q "'Submitter'=\"tester\" AND ('Create Date' >|
\"5/9/2007\" AND 'Create Date' < \"5/16/2007\")"
-Z Internal format qualification file name — File name containing the query in Remedy internal format.
-z Client tool format qualification file name — File name containing a regular query.
-w (or Authenticator — Name of the external authentication string or Windows NT domain. This is related to the Login
-W) window's Authentication field. See Authentication String Alias introduction (see page 1330).
-a Port number — Port number to which to connect the server.
-f (or Form name — Form that is exported. The -f (or -s) option can be repeated multiple times if there are several forms to
-s) export. If multiple servers are selected, each server is searched for the form, and the first one found is all that is
exported. To control this, specify only one server environment for the operation. If the -f (or -s) option is not specified,
the system exports all available regular data forms. It does not export join or external forms.
-t Type of file to write — File type for the output file: arx, csv, or xml. If not specified, the default of arx is used.
-O Forces override — If the user has already logged in as this same user from a different IP address, this option tells the
server to use the new IP address of the runmacro client and invalidates the old IP address.
Note: This option does not apply to users with administrator permissions.
Enabling the Data Import utility


Localization tips for importing (see page 1991)

Importing with a mapping file (see page 1991)
Importing without a mapping file (see page 1991)
Importing in a multithreaded environment (see page 1992)
Data Import command-line utility options (see page 1993)
Data Import utility scenarios (see page 2000)
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 (see page ).)
You can import with or without a mapping file. See Importing with a mapping file (see page )
and Importing without a mapping file (see page ).
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 arapiext90_build001.jar and arapi90_build001.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_90\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%arapi90_build001.jar;%APIDROP%arapiext90_build001.jar;

com.bmc.arsys.apiext.data.DataImport [options]
For a list of available options, see Data Import command-line utility options (see page ).
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:
arapi90_build001.jar

1.
arapiext90_build001.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 arapiext90_build001.jar and arapi90_build001.jar
are installed.
JAVA_HOME — The location of your JDK (for example, /usr/Java/jdk1.5.0_14 ).
Path
For example:
#!/bin/sh
APIDROP=ARSystemHome/api/lib
JAVA_HOME=${JAVA_HOME:-jdkPath}
export JAVA_HOME
PATH=$JAVA_HOME/bin:$PATH:$APIDROP
export PATH
Note
Either execute the following command from the ARSystemHome/api/lib

directory or set the Library Path and the Path variable using the following
command: export LD_LIBRARY_PATH=$ARINSTALL/api
/lib:$ARINSTALL/bin:$LD_LIBRARY_PATH export PATH=$ARINSTALL
/api/lib:$ARINSTALL/bin:$PATH
4. Enter the following command to use the Data Import utility on UNIX:
exec java -cp $APIDROP/arapi90_build001.jar:$APIDROP/log4j-1.2.14.jar:$APIDROP

/arapiext90_build001.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 (see page 1993
).

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 (see page ).
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 (see page ).
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

Using the custom_options.xml file (see page 1997)

Using the options.xml file (see page 1997)
Use the following format in the command line. Items between square brackets are optional.
com.bmc.arsys.apiext.data.DataImport -u userName -p password

-x serverName [-w externalAuthenticationString] [-r rpcNumber]
[-a portNumber] [-custom custom_optionsFilePath]
[-f destinationFormName] -o dataFilePath
[-filelist listOfFiles] [-z options.xmlFilePath]
[-threads numberOfThreads] [-l logFilePath]
[-e duplicateField] [-b bulk size] [-g activateBulkMode]
[-n suppressFilters][-s suppressassociations] [-t multiMatchOption] [-v] [-i]
[-D duplicateIDOption] [-q option] [-c option] [-h 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 Option name Description
-u User name Required login parameter that identifies the user account.
Note: Every cross-platform CLI command opens a separate Data Import session, executes the
command, and logs out. Therefore, you must log in with every command. If Data Import does not
find the user name, Data Import prints the usage messages and exits.
-p Password Password for the user account. If the user account has no password, omit the -p option.
-x Server name The server to log in to. If you do not specify the -x option, the server name in the mapping file is
used.
-w Authentication Name of an external authentication string or Windows NT domain. This is related to the Login
string window's Authentication field, which is discussed in Setting up an authentication alias (see page
1328).
-r RPC program Private server, for example, if a dedicated import server is available. If you do not specify the -r
number 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.
- Path to Specifies the path to the custom_options.xml file, which is used to specify date and time formats,
custom custom_options. the separators to be used, and other information. You can use this option if the source data file is
xml in CSV or ASCII format. See Using the custom_options.xml file (see page 1997).
Note: During installation, a sample empty custom_options.xml file is installed in the installation
folders for Developer Studio and Data Import. You can change the name and store it anywhere.
-f Destination form Importing with a mapping file

name
Destination form name — Name of the form to import data into. If you do not specify the -f option,
the form specified in the mapping file is used.
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 Data File Path

Path to a directory of data files — For multithreaded environments, the -o option specifies
the path to the directory that contains the data files to import.
Path to data file — For single-threaded environments, the -o option specifies the file that
contains the data files to import.
If you do not specify the -o option, the data file specified in the mapping file is used.
-z Path to the Specifies the path to the options.xml file, which contains the data import commands and the
options.xml file 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 (see page 1997).
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 The data files can be of any type (for example, ARX, CSV, XML, and ASC ). All of the data is
multithreaded imported into the form designated with the -f or -M option. If you do not specify the -filelist option,
environments the command imports all the data files in the directory specified with the -o option, regardless of
only) List of data file type.
files to import
- (For If you do not specify the -threads option, the default of 50 threads is used. If the number of files in
threads multithreaded the data directory or number of files you specify in the -filelist option is less than the -threads
environments value or the default value (50), the number of threads used is equal to the number of files in the
only) Number of data directory or number of files specified in -filelist option.
threads in the
pool. Note: Make sure that your hardware configuration can handle the number of threads that you
enter.

-l Full path name Use this option to log details of the import execution.
of the log file
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 The options are:

log files appear
0 (the default) — Logs appear on the console.
1 — Logs do not appear on the console. They appear in the log file specified with the -l
option. If the -l option is not used, the logs will not be created.
-e Duplicate field Field ID of the field to check for duplicate data. For example, for the Short Description field, enter 8
. To specify multiple values for a single schema, separate them with commas and double quotation
marks (for example, "2,4,8" ). The maximum number of IDs you can specify is 6. From this release
of BMC Remedy AR System, you can now specify multiple values for multiple schemas. For this,
separate the schema names (and their values) by a semi-colon and the values by commas (For
example, SchemaName=1,2,3; SchemaName=4,7,8 ). The maximum number of IDs you can
specify is 6. Make sure that the source data file includes values for all the fields that are being
used for checking duplicate data. When -e option is omitted, then Request ID field (field ID 1) is
used. Additionally, if the -e option is not used for importing records, the Data Import utility uses
bulk mode to import records. (See the -b option for more information about the bulk size.)
-b Bulk size Specifies the number of records to process in bulk simultaneously. For AR System 7.1.00 and later
versions, the default size is 100.
Note: If the -e option is used, records are imported individually. If the value of the -b option is set
to 0, bulk mode will not be used.
-g Activate Bulk If the -e option is used, the bulk transaction mode is switched off by default. In this case, you can
Mode still activate the bulk transaction mode using the -g option.
Note: The bulk transaction mode is purposefully switched off with -e option as it gives different
results than sequential import when there are duplicate records within the data file itself. To
forcefully use bulk mode when the -e option is used, you can use the -g option. You can decide
whether you want to use the -g option when there are duplicate records in your data files. For
example, you must use the "-g 1 " value in the Java Import command line to use the bulk mode. If
any value other than "-g 1 " is used, the force bulk mode is not activated.
-n Suppress filters Suppresses the merge filters during merging of entries on forms.
-s Suppress Setting this flag causes the server to suspend enforcement of associations on entries getting
associations imported. Associations are still enforced on other entries affected by workflow that might be
triggered by entries getting imported. The server will only honor this flag if the user of the import
tool is an administrator.
-t Multiple match Use when more than one entry matches. Enter a value of 3 to affect the first match, and a value of
options 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 If specified, this option will ignore the default values of fields if the value in the data file is null or
values 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 Suppresses the required field property for non-core fields. The options are 1 (on) and 0 (off) .
field property for
non-core fields.
-c Truncates Truncates character values that are longer than the field length for character fields. The options
character values are 1 (on) and 0 (off) .
-h Suppresses If supplied, the $PATTERN$ field limit is ignored. The options are 1 (on) and 0 (off) .
pattern matching
for fields
- Specifies the The character set name must be supplied as listed in the IANA Charset Registry.
charset character set
used in the data
file
-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 (see page ).
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 (see page 2001)

With a mapping file scenarios (see page 2001)

Without a mapping file scenarios (see page 2002)
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 (see page 1330).
-x Specify the name of the server to connect to.
-t Specify the TCP port number to connect to. If the port number is unknown, use -t 0.
-O Use this option to overwrite existing attachments and data file. The following values are valid for this option:
1 - Overwrite existing attachments and data file.

0 - Do not overwrite existing attachments and data file.
-form Specify the name of the form from which you want to export data. To export data from multiple forms, use a
comma-separated list of form names in the following format:
-form "form1, form2, form3"
If the -form option is not specified, an error message is logged in the artools.log file and the utility stops running.
-datafile Specify the name and path of the file in which to store the data. If you do not specify the file extension, the utility
adds the .arx extension to the data file.
-e Specify the field IDs for which you do not want to export data. You can use a comma-separated list in the following
format:
-e "3, 7"
-T Specify the size of the transaction. The default size is 100 records.
-L Specify the log file path. To specify a log file path, use the following format:
-L c:\ARExport\exportlog.log
Note
Ensure that the log file path exists and that the file extension is included in your command.
When you specify the -L option, logs are not generated in the default artools.log file located in the
<ARServerInstallationDirectory>\Arserver\Db folder. For information about the logging for the AR Export
command, see Logging for the arexport command. (see page 2006)
-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

Option Description
Do not use a field label as the qualification string. You must use a field name or a field ID as the
qualification string.
-delim Specify the delimiting character to use when you specify multiple values to an option. By default, a comma is the
delimiting character. Use the -delim option with the -form and -e options that take multiple values as input.
After you specify a delimiter, you must use the same delimiter for all the options that take multiple values as input.
Not using the same delimiter might cause incorrect data extraction.
For example, if you enter the following command, the AR Export utility ignores the field IDs (4, 6) listed in the -e
option and includes the data for all the fields:
arexport.bat -u <userName> -p <password> -x <serverName> -delim ";" -form "form1;form2" -e 4,6
The following command successfully extracts the data by excluding the data of the fields with IDs 4 and 6.
arexport.bat -u <userName> -p <password> -x <serverName> -delim ";" -form "form1;form2" -e 4;6
Use the -delim option if the form name itself contains a comma. For example, use the following format to specify
a semicolon as the delimiter if the form name contains a comma:
arexport.bat -u <userName> -p <password> -x <serverName> -form "Test,form1;form2" -datafile

<dataFilePath> -delim ";"
Note
Test,form1 is the name of the form containing a comma.
- Use this option to add a time stamp to the folder containing form attachment data. This option has the following
timestamp values:
1 - Do not add a time stamp.

0 - Add a time stamp.
-timeout Specify the timeout period for connecting to the server. You can specify Normal, Long, and XLong seconds after
which the timeout occurs. Use the following format to specify the timeout values:
-timeout Normal:Long:XLong
The default timeout values for Normal:Long:XLong are 120:300:1800.
Note
You must specify all three values even if you want to set one timeout value.
For example, if you want to set the Long timeout value to 400 seconds, use -timeout 120:400:1800.

Example
Consider a situation in which a user with the user name Demo needs to export data from a form
named Form1 into the data file c:\ARExport\data.arx, using a qualification string such as 'FieldID'="
000000001123" with transaction size 50, and needs to exclude data for fields with IDs 8 and 5. The
arexport command would look like the following:
Windows
arexport.bat -u Demo -x myServer -p "abc" -form "Form1" -datafile "c:\ARExport\data.arx"

-T 50 -e "8, 5" -q "'1' = \"000000001123\""
UNIX
arexport.sh -u Demo -x myServer -p "abc" -form "Form1" -datafile "/ARExport/data.arx" -

T 50 -e "8, 5" -q "'1' = \"000000001123\""
Logging for the arexport command

If an exception occurs when the form data is being exported, the exported records of that form are
rolled back and removed from the .arx file and the details are logged in the artools.log file.
On Windows, the artools.log file is located in the <ARServerInstallationDirectory>\Arserver\Db

folder.
On UNIX, the artools.log file is located in the <ARServerInstallationDirectory>\db folder.
Using the Request ID to improve performance or security

This section contains information about using the Request ID to improve the performance or
enhance the security of your BMC Remedy AR System environment:
Working with the Request ID field (see page 2007)

Changing the next available ID for new requests (see page 2008)
Changing the Request ID field length or prefix (see page 2009)
Preserving Request ID field values (see page 2010)
Changing Request ID field values to a new format (see page 2010)
Updating the Request ID field in other AR System tables (see page 2018)
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 (see page ).

Changing the Request ID field length or prefix (see page ).

Preserving Request ID field values (see page ).

Changing Request ID field values to a new format (see page ).
Updating the Request ID field in other AR System tables (see page ).
Changing the next available ID for new requests

In this topic:
Database command scenarios for changing the next available request ID (see page 2008)
The Request ID is used to automatically generate the unique index number attached to each BMC
Remedy AR System request. Under some conditions, you might need to reset the next available
ID. For example, you might need to establish different ranges for a similar form on two different
servers, or you might need to reserve a range of numbers for later use.
Note
Do not change the next available ID to a number lower than the greatest existing ID. The
Request ID field value must be unique within BMC Remedy AR System, and resetting the
ID to a lower number could conflict with existing Request ID field values. If you try to
submit a request with an existing ID, BMC Remedy AR System returns an error and
prevents the request from being submitted until the conflict is resolved.
If you must change the next available ID, change it when the system is not in use to avoid conflicts
with users who are submitting new requests.
To change the next available ID for a form in an SQL database
1. Stop AR System server.

2. Using any front-end tool that provides direct access to an SQL database, log in as a user
with write access to the AR System tables.
3. Connect to the AR System table area.
4. Find the Request ID field for the form that you want to modify.
5. Update the next available ID.
6. Restart the AR System server.
Database command scenarios for changing the next available request ID

The following scenarios show how to change the next available ID for DB2 Universal, Oracle,
Microsoft SQL Server, and Sybase databases. In the scenarios, the next available ID for a form
named ZZZ is changed from the current value of 1291 to a new value of 25000.
DB2 Universal scenario
>open DB2 command center

Connect to AR System.
>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 (see page ).

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

Using an AR Export file to change the request ID field format (see page 2011)
Editing the .arx file (see page 2012)
Using SQL commands to shorten the Request ID field (see page 2013)
Using SQL commands to lengthen the Request ID field value (see page 2017)

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 (see page ).
Using SQL commands to shorten the Request ID field (see page ).
After implementing one of those methods, see Updating status history tables (see page 2018) and
Updating attachment tables (see page 2018).
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. See Setting up a new report (see page 957).
3. Perform the following to export the results of the BMC Remedy AR System report to the .arx
file format:
a. Select the report from the list.
b. In the Destination field, select File.
c. In the Format field, select .arx output format for the report.
d. Run the report as described in Running reports (see page 947).
For more information, see Exporting BMC Remedy AR System reports (see page 951).
4. Edit the file to change the format of the Request ID field.
See Editing the .arx file (see page ).
5. In the browser, delete all requests in the form.
6. In Data Import, choose File > New Mapping.
7. In the Source Data File field, enter the .arx file you edited.
8.
8. In the Source Form Name, enter the form from which you created the .arx file.
9. 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.)
10. Click Auto Map to map the fields.
11. Click the Options tab.
12. Under the Data Handling panel, select the following options:
Make Non-Core Required Fields Optional
Disable Pattern Matching
13. Under the Duplicates panel, select Reject Duplicate Records from the Handle Duplicate
Request IDs By list.
14. 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.
4. Replace all instances of:

DATA "00000000
with:
DATA "ABC
5. Save the changes to the file.
To edit the .arx file in UNIX
1. Open the file in a text editor.

2. Type the following command:
g /^DATA "00000000/s//DATA "ABC/
3. Save and close the file.
Using SQL commands to shorten the Request ID field

Changing existing Request ID field value format when the Request ID does not have a prefix
(see page 2015)
Changing existing Request ID field value format when the Request ID has a prefix (see
page 2016)
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
schemaID that 43 is the schema ID and 536870924 is the field ID. In many cases, the form has more than one long text or diary
C fieldID field. This format is used for backward 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
schemaID ID. See the Database Reference Using relational databases with BMC Remedy AR System (see page 2030).
B A table that contains a list of all the attachments and related information for each record in your form. A table named
schemaID B43 indicates that 43 is the schema ID. See The attachment tables for a form (see page 2025).
B A table that contains the actual Binary objects for attachment fields in your form. A table named B43C536870924
schemaID indicates that 43 is the schema ID and 536870924 is the field ID. In this example, the field ID for the attachment field
C fieldID is 536870924. In some cases, the form has more than one attachment field.
Note

For T schemaID and B schemaID tables, the request ID column of the table is always
named C1. For the H schemaID, T schemaIDC fieldID, and B schemaIDC fieldID tables,
the Entry ID column is equivalent to the C1 column.
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 (see page ) 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 (see page 2013) and The status history table for a form (see page 2024).
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 page 2013).
See the The attachment tables for a form (see page 2025).
Understanding the AR System database

This section contains information about the AR System database:
Table updates for AR System form changes (see page 2019)

Understanding the relationship between forms and database tables (see page 2023)
Using relational databases with BMC Remedy AR System (see page 2030)
Table support for server group tables (see page 2036)
The AR System data dictionary (see page 2037)
Database column types used for AR System fields (see page 2047)
Related information for supported databases (see page 2050)
Table updates for AR System form changes

When you restructure a regular form by adding, deleting, or changing the length of fields, BMC
Remedy AR System restructures the underlying database to reflect those changes.
Table updates when adding fields to a form (see page 2020)

Table updates when deleting fields from a form (see page 2020)
Table updates when changing character field lengths (see page 2020)
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 (see page 2023).
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.
the table.
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 Adds a varchar column to the main data table; copies the data from the clob
to <= 4000 bytes. column to the new column; deletes the old column.
Decreases the length of a field from <= 4000 Performs no restructuring.

bytes to less than 4000 bytes.
Increases the length of a field from <= 4000 bytes Adds a clob column to the main data table; copies the data from the varchar
to > 4000 bytes. column to the new column; deletes the old column.
Increases the length of a field from > 4000 bytes Performs no restructuring.
to 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.
the table.

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 <= Alters the index to increase the index size and preserve the existing
32K data.
Lengthens a field that is <= 32K. The new length is > Reindexes the field to generate a new index. a
32K.
Shortens a field that is > 32K. The new length is <= Reindexes the field to generate a new index. a
32K.
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 main data table for a form (see page 2024)

The status history table for a form (see page 2024)
The attachment tables for a form (see page 2025)
Currency columns for a form (see page 2026)
Indexing AR System tables (see page 2027)
SQL view creation for a form (see page 2029)
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 (see page 2038), 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 (see page ).
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 (see page 2038), 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 (see page 3125).
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 (see page
2038), 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 (see page 2038), 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 (see
page ).
Currency columns for a form

Where a field in a form typically has one corresponding column in the main data table, the currency
field has several columns and, therefore, a unique naming convention to distinguish the extra
columns. Whereas typical fields follow the naming convention described in The main data table for
a form (see page ) (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
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 Value of specified type of functional currency
on)
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 in BMC Remedy ITSM Deployment
documentation.
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.
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
Microsoft SQL Server
Oracle
Sybase ASE
Note
For the most accurate information about supported platforms and software, Compatibility
matrix in the BMC Remedy ITSM 9.0 online documentation.
Each type of relational database behaves differently with regard to search qualifications, wildcards,
and so forth. The following topics describe these differences.
Using IBM DB2 Universal Database with BMC Remedy AR System (see page 2032)
Using Microsoft SQL Server with BMC Remedy AR System (see page 2033)
Using Oracle with BMC Remedy AR System (see page 2035)
Using Sybase with BMC Remedy AR System (see page 2035)
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 (see page ).
For information about different behaviors and requirements for installing BMC Remedy AR System
with specific databases, see Preparing your database in BMC Remedy ITSM Deployment
documentation.
For information about configuration options and parameters associated with specific databases,
see ar.cfg or ar.conf (see page 1065).

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 (see page 1339) 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. 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.
Using Microsoft SQL Server with BMC Remedy AR System

Microsoft SQL Server behaviors that you need to consider are described in the following sections.
Diary and Character field qualifications

When you specify search criteria for a field that contains more than 8000 characters or a diary
field, you must use the LIKE operator. If you use any other relational operator, you receive an
error.
Case sensitivity in queries

By default, the Microsoft SQL Server search criteria are in dictionary order and are case-
insensitive. You can, however, specify an option that enables case-sensitive searches. For more
information, see your Microsoft SQL Server documentation.
Reducing deadlocks by using snapshot isolation

Microsoft SQL Server 2005 provides the "snapshot" isolation level, which allows a transaction to
read the last committed version of the data that is currently being changed. Thus, the transaction's
view of the data is consistent with the state of the data when the transaction began without being
blocked by other transactions. This reduces the possibility of deadlocks.
Warning
Some processing overhead occurs due to the creation of a temporary database with a
large size, and the storage and retrieval of versioned data.
For more information about the snapshot isolation in SQL Server, go to http://msdn.microsoft.com
/en-us/library/ms130975.aspx.
To use a snapshot isolation level with the AR System database
1. Stop the AR System server to ensure that all connections to the AR System database are
closed.
For a server group or a shared database, stop all of the AR System instances.
2.
2. To verify whether the appropriate isolation level is set for the AR System database, enter:
SELECT is_read_committed_snapshot_on FROM sys.databases where name = 'ARSystem'
3. To set the snapshot isolation level, enter:
ALTER DATABASE ARSystem SET READ_COMMITTED_SNAPSHOT ON
4. Restart the AR System server. Optionally, to revert to the original setting, use the following
commands in the same sequence as mentioned:
ALTER DATABASE ARSystem SET READ_COMMITTED_SNAPSHOT OFF
Improving performance with parameterization

The AR System server uses dynamically built queries that need to be compiled and recompiled
frequently. By default, the AR System database uses simple parameterization.
Forced parameterization converts any literal value that appears in a SELECT, INSERT, UPDATE,
or DELETE statement to a parameter during query compilation. A parameterized query requires
less recompilation, thereby improving performance.
Tip
Do not use forced parameterization in environments that rely heavily on indexed views
and indexes on computed columns. Error reporting for forced parameterization might
differ from that of simple parameterization. Only experienced database administrators
should use forced parameterization after determining that its usage does not adversely
affect performance.
For further information about forced parameterization, go to http://msdn.microsoft.com/en-us/library

/ms175037.aspx.
To use forced parameterization with the AR System database
1. To set forced parameterization, enter the following SQL command:
ALTER DATABASE ARSystem SET PARAMETERIZATION FORCED
You can set this attribute without interrupting the existing database connections.
2. To revert to the original setting, enter the following SQL command:

ALTER DATABASE ARSystem SET PARAMETERIZATION SIMPLE
Using Oracle with BMC Remedy AR System
(see page 2035)

Diary and Character field qualifications (see page 2035)
Case sensitivity in queries (see page 2035)
Diary and Character field qualifications

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 (see page 1065).
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 in BMC Remedy ITSM Deployment documentation.
Case sensitivity in queries

By default, the Oracle database is case sensitive. To enable a case-insensitive search for fixed-
length text fields in BMC Remedy AR System server that uses an Oracle database. See Oracle
case-insensitivity in Tuning an Oracle server in BMC Remedy ITSM Deployment documentation.
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.
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 (see page 342).
The AR System data dictionary

In this topic:
The initial table of the AR System data dictionary (see page 2040)
The schema table in the AR System data dictionary (see page 2040)
The field table in the AR System data dictionary (see page 2041)
The menu table in the AR System data dictionary (see page 2042)
The image table in the AR System data dictionary (see page 2042)
The filter table in the AR System data dictionary (see page 2042)
The escalation table in the AR System data dictionary (see page 2043)
The active link table in the AR System data dictionary (see page 2043)
The workflow mapping tables in the AR System data dictionary (see page 2044)
The container table in the AR System data dictionary (see page 2044)
The overlay and custom object columns in the AR System data dictionary (see page 2045)
The association table in the AR System data dictionary (see page 2046)
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 charVal data type.
The image table includes unique indexes on the following fields:
imageID — AR System assigns a unique image ID to each stored image.

name — You assign a unique name to an image object when you create it.
For backward compatibility with pre-7.5.00 AR System clients, the AR System server converts the
charVal reference to a data string before transferring it to the client.
Two XML ENUM data types for exporting images (AR_STRUCT_ITEM_IMAGE and
AR_STRUCT_ITEM_XML_IMAGE ) and an export format (image ) are added. For more
information about image objects, see Working with images (see page 2559).
The filter table in the AR System data dictionary

The filter table contains an entry for each filter, and tags each with a filterId. Tables associated
with the filter table (linked by filterId ) provide the details about the various actions defined for each
filter:

filter_call filter_notify_ids
filter_exit filter_process
filter_goto filter_push
filter_gotoaction filter_serviceaction
filter_log filter_set
filter_message filter_sql
filter_notify
The escalation table in the AR System data dictionary

The escalation table contains an entry for each escalation, and tags each with an escalationId.
Because escalations and filters are so tightly linked, the information about actions for escalations is
stored in the same tables as the filter actions. The escalationId and the filterId are unique within
the table, so a single ID identifies either a filter or an escalation.
The active link table in the AR System data dictionary

The actlink table contains an entry for each active link, and tags each with an actlinkId. Tables
associated with the actlink table (linked by actlinkId ) provide the details about the various actions
that are defined for each active link:
actlink_macro actlink_goto
actlink_macro_parm actlink_exit
actlink_set actlink_call
actlink_process actlink_close
actlink_message actlink_commit

actlink_set_char actlink_open
actlink_dde actlink_sql
actlink_gotoaction actlink_push
actlink_wait actlink_auto
actlink_serviceaction
The support_file table stores report definitions. Finally, the table actlink_group_ids contains the
list of groups that can execute the active link.
The workflow mapping tables in the AR System data dictionary

A set of mapping tables associates each filter, escalation, or active link with all its forms, allowing
administrators to create shared workflow. The filter_mapping table contains the filterId and
schemaId for each entry, creating a link between each filter and form. The escal_mapping table
associates escalations with forms by storing the escalationId and schemaId for each entry. In a
similar way, the actlink_mapping table associates active links with forms by storing the actlinkId
and schemaId for each entry.
The container table in the AR System data dictionary

The arcontainer table contains an entry for each container, and tags each with a containerId.
Containers are used to define guides, applications, packing lists, workspaces, and web services.
The three main fields in the table are:
containerId — The unique internal ID for the container.

name — The administrator name for the container.
containerType — The type of container.
The following set of tables holds information associated with the container definition:
arctr_group_ids — Defines which groups have access to the container.

arctr_subadmin — Defines which groups have subadministrator access to the container for
containers that are not owned.
arreference — Defines the references for each container.
arref_group_ids — Defines group access permissions for external references.
cntnr_ownr_obj — Lists the owners for the container.

A list of references defines the components that belong to each container. For example, a
container might reference forms, workflow objects, and other internal and external objects that
make up an application or guide. Each container can have zero, one, or multiple references. Each
reference is identified by the containerId of the container to which it belongs, and by the
referenceId that identifies the object itself.
All references are described by reference type, data type, reference order number, label, and
description. Internal references store the referenceObjId. External references store a short value
or long value that describes the external reference. The arref_group_ids table can have zero,
one, or multiple group entries that define group access permissions for each external reference.
Each entry describes a groupId permitted to access an external reference.
For more information about using containers to create guides, see Containers and structures (see
page 3649). For more information about the data structures used to define containers, see
Containers and structures (see page 3649).
The overlay and custom object columns in the AR System data dictionary
The following columns are added to the actlink, arcontainer, arschema, char_menu, escalation,
field, filter, image, and vui tables in the AR System database to support the overlays and custom
objects:
overlayProp(int) — Holds a bitmask value that specifies the overlay state of an object. The
values are:
0 (unmodified)
1 (overlaid)
2 (overlay)
4 (custom)
By default, this column is blank, which is the same as 0 (unmodified). When an
overlay is created, the create overlay operation sets this column to 1 in the overlaid
object and to 2 in the overlay object.
overlayGroup(nvarchar(254)) — Identifies the overlay group to which an object belongs.
The values are:
0 (does not belong to an overlay group)
1 (belongs to the overlay group)
An object can belong to only one overlay group.
All overlay and custom objects have 1 in this column. Unmodified and overlaid
objects always have 0 in this column.
resolvedName (nvarchar(254)) — Holds the name of the overlaid object.
overlayExtended(int) - Defines whether an object is extended. The values are:
0 (not extended)
1(extended)

Note
When you use the get function of the AR System driver utility for an object,
it displays the overlayProp and overlayGroup values for all objects, except
the unmodified ones.
The following table shows the values for the overlay* columns by object
customization type:
Database overlay column values by object customization type

Object type Database overlay column values
overlayProp overlayGroup
Unmodified 0 0
origin
Overlaid 1 0
Overlay 2 1
Custom 4 1
In addition to the preceding columns, the following columns were added to the
arschema and vui tables:
resolvedSchemaId int (arschema)
objProp nvarchar(254) (vui)
Note
For each overlay, an entry is added to the baseline object table. Nonetheless, field and
form overlays are not treated as individual objects in the database. Instead, they are
treated as subsets of the overlaid object properties because they share data with the
overlaid object. All other types of overlays are treated as individual objects, although they
remain dependent on their overlaid objects and are tightly coupled with them.
For more information about overlay and custom objects, see Customizing applications using
overlays and custom objects (see page 3031).
The association table in the AR System data dictionary

The association table contains an entry for each association, and tags each with a associationId.
Tables associated with the association table (linked by associationId ) provide the details about
the various actions defined for each association:
association_indirect

association_pkfk_mapping
For more information about associations, see Associations overview (see page 117).
Database column types used for AR System fields

In this topic:
DB2 column types used for AR System fields (see page 2047)
Microsoft SQL Server column types used for AR System fields (see page 2048)
Oracle column types used for AR System fields (see page 2048)
Sybase column types used for AR System fields (see page 2050)
The following sections list the column types used for AR System fields in each database type
supported by BMC Remedy AR System.
Note
Control, display-only, page, page holder, table, table column, trim, and view fields do not
require storage in database tables, so they are not listed in this section.
DB2 column types used for AR System fields

The following table shows the DB2 column types used for each AR System field type whose values
are stored in database tables.
DB2 column types used for AR System fields
AR System field type DB2 column type
Attachment blob (up to 1 GB)
Character with a maximum length of 4000 or fewer bytes varchar
Character with an unlimited length or a maximum length of more than 4000 bytes clob (up to 1 MB)
Currency (a group of columns composed of a combination of the specified column decimal, varchar, and integer
types)
Date integer
Date/Time (time stamp) integer
Decimal decimal
Diary clob (up to 1 MB)
Integer integer
Real float

AR System field type DB2 column type
Selection integer
Time integer
Note
Previously created fields that use longvarchar types continue to use longvarchar.
Microsoft SQL Server column types used for AR System fields

The following table shows the Microsoft SQL Server column types used for each AR System field
type whose values are stored in database tables.
Microsoft SQL Server column types used with AR System fields
AR System field type SQL Server column type
Attachment up to 2 GB image
Character with an unlimited length or a maximum length of more than 8000 bytes text
Currency (a group of columns composed of a combination of the specified column decimal, varchar, and int
types)
Date int
Date/Time (time stamp) int
Decimal decimal
Diary text
Integer int
Real float
Selection int
Time int
Oracle column types used for AR System fields

Configuring process administrator capabilities (see page ) shows the Oracle column types used
for each AR System field type whose values are stored in database tables.
Oracle column types used with AR System field types

AR System field Oracle column type

type
Attachment up to blob For the Oracle RDBMS, the default maximum attachment size is 2 GB. (This was increased from 1 MB
4 GB to 2 GB.) To adjust the maximum attachment size, update the Db-Max-Attach-Size configuration parameter
in the AR System Administration: AR System Configuration Generic UI form. For more information, see
Configuration settings C-D (see page 1168). The maximum value is limited by your server operating system
and configuration.
Note
Attachment fields created by a pre-7.0 BMC Remedy AR System server remain a long raw data
type. New attachment fields use the Oracle blob type.
Character with a varchar

maximum of
4000 or fewer
bytes
Character with clob The AR_SERVER_INFO_ORACLE_CLOB_STORE_INROW server information setting controls Oracle
an unlimited CLOB storage. It takes these values:
length or a
maximum length TRUE --- CLOBs are created "in row."
of more than
4000 bytes
Large in-row CLOBs can degrade CPU performance, but small CLOBs can improve performance
because the CLOB data can be fetched with the row from the database. AR System in-house
application developers convert any character field designed to contain more than 255 bytes into a
CLOB (database input length = 0). Typically, such fields are not expected to hold large amounts of
data. Therefore, unless you expect to store unusually large amounts of data in CLOBs, set this
option to TRUE before installing AR System applications so that all database tables for
applications are created in-row.
FALSE (default) --- CLOBs are created "out row."
Out-row CLOBs can cause the database to grow rapidly. Use out-row CLOBs only when your
database storage is not limited and your CLOBs are expected to hold large amounts of data.
Note
If a field contains more than 4000 characters, the CLOB is stored out row no matter which
value is specified for this server setting.
For more information about the storage and performance effects of using in-row versus out-row
CLOBs, see Using Oracle CLOBs with BMC Remedy AR System (see page 697). The
corresponding setting in the AR System server configuration file is Oracle-Clob-Storage-In-Row. |

Currency (a group of columns composed of a decimal, varchar, and number (15, 0 )

combination of the specified column types)
Date number (15, 0 )
Date/Time (time stamp) number (15, 0 )
Decimal decimal
Diary clob For more information, see the preceding Oracle data type
description for character fields with unlimited length.
Integer number (15, 0 )
Real float
Selection number (15, 0 )
Time number (15, 0 )
Sybase column types used for AR System fields

The following table shows the Sybase column types used for each AR System field type whose
values are stored in database tables.
Sybase column types used with AR System fields
AR System field type Sybase column type
Attachment up to 2 GB image
Character with an unlimited length or a maximum length of more than 255 bytes text
Currency (a group of columns composed of a combination of the specified column decimal, varchar, and int
types)
Date int
Date/Time (time stamp) int
Decimal decimal
Diary text
Integer int
Real float
Selection int
Time int
Related information for supported databases

The following table lists suggested reading for databases that BMC Remedy AR System supports.
Depending on the version of your database, the titles might differ slightly.

Database type Suggested reading
All
Introduction to Database Systems by C.J. Date
DB2
A Complete Guide to DB2 Universal Database by Don
Chamberlin
Oracle
SQL Reference Manual
Oracle Administrator's Guide
Sybase
Sybase Commands Reference Manual
Sybase Administration Guide
Microsoft SQL
Server Transact-SQL Desk Reference: For Microsoft SQL Server
Microsoft SQL Server 2000 Administrator's Companion
SQL definitions of the data dictionary tables

The SQL commands that define the data dictionary for the AR System database are in the
following files:
ARSystemServerInstallDir/Logs/arsystem_create_tab.txt
This file is created when you install the AR System server for the first time or when you
overwrite your current server installation. It contains all the SQL commands required to
create the default data dictionary for your AR System database type. This file is not deleted
or modified when you upgrade your server.
ARSystemServerInstallDir/Logs/arsystem_upgrade_sql.txt
When you upgrade your AR System server, this file is created to record the differences
between the SQL commands used to create the data dictionary in your previous version of
the AR System database and in your upgraded version.
Each subsequent upgrade overwrites this file. Therefore, to save its contents, rename it
before performing another upgrade.
The names of these files are the same for all database types.
To view the contents of these files in a reader-friendly format, open them in WordPad.
For more information about the SQL commands that define the AR System data dictionary,
see the following documents:
Database type Document
DB2 Universal A Complete Guide to DB2 Universal Database

Database

Database type Document
Microsoft SQL Server Transact-SQL Desk Reference: For Microsoft SQL Server
Oracle Oracle SQL Reference Manual
Sybase Sybase Commands Reference Manual
Migrating applications and data between AR

System servers
This section contains information about migrating applications and data between AR System
servers:
Migration overview (see page 2052)

Navigating the BMC Remedy Migrator interface (see page 2063)
Setting BMC Remedy Migrator options (see page 2096)
Performing migrations (see page 2120)
Working with migration scripts (see page 2169)
Using migration reports (see page 2180)
Migration overview
This section contains information about the migration process and modes:
BMC Remedy Migrator process overview (see page 2052)

How objects are migrated (see page 2054)
Migration modes (see page 2057)
Managing embedded server names (see page 2058)
Cache file management overview (see page 2062)
BMC Remedy Migrator process overview

BMC Remedy Migrator automates the process of transferring objects and data from one source
(server or file) to another. For example, you can develop workflow applications on a development
server (source) and use BMC Remedy Migrator to transfer them to a production server
(destination), ensuring the integrity of all migrated changes.
With BMC Remedy Migrator, you connect to one or more AR System servers and then select a
source and destination for the objects, fields, or data you are migrating. The following sections
refer to two server types:
A source server, where you modify or update your applications that are in development.
A destination server, where users work with the current versions of your applications that
are in production.

Note
During migration, the source server should show no impact in performance. Impact to the
destination server can vary from minimal to heavy, depending on the number of changes
being made, the size of the objects, server speed, network bandwidth, and traffic.
You can perform migrations using either of two methods: immediate migrations or scripted
migrations.
Immediate migrations run in Migration mode.

Scripted migrations run in Scripting mode. In this mode, you create scripts that you can
save, schedule, and reuse. You can also use the Before and After commands to run a
program before or after the script executes.
To migrate objects, you select the objects you want to migrate and start the migration using
menu commands or by dragging the objects to the destination server.
A migration consists of the following steps:
1. BMC Remedy Migrator packages the selected objects.

2. BMC Remedy Migrator expands the package and looks for join forms, table fields in forms,
related objects, and required menus.
3. BMC Remedy Migrator produces a migration results file.
4. The migration begins.
BMC Remedy Migrator migrates the objects in a specific sequence (see Migration sequence (see
page )), and then generates a migration result report.
Migration process

When a migration begins, BMC Remedy Migrator retrieves the next object from the results file and
compares the source object to the destination object, if any. Based on the results, BMC Remedy
Migrator performs the following actions:
Creates the object, if it is missing, on the destination server.

Modifies the destination server if the object is different from what is on the source server.
For Form and Related migrations, BMC Remedy Migrator performs the following actions:
Marks the objects to delete or disable if they are not in the source server.
Deletes or disables all marked objects (active links, filters, or escalations) that are on the
destination server.
How objects are migrated

This section explains how BMC Remedy Migrator moves objects and manages join forms, table
fields, and Form and Related Object migrations, and how BMC Remedy Migrator manages
embedded server names.
Form migrations
When migrating a form from one server to another, BMC Remedy Migrator migrates the form and
the menus referenced by the form. This makes sure that the form works correctly when a user
opens it in BMC Remedy Mid Tier. In some cases, BMC Remedy Migrator tries to migrate more
than the form and menus, as described in the following sections.

Migrating join forms

When migrating a join form, BMC Remedy Migrator builds a tree that represents the structure of
the join form. For example, to migrate Join Form A, BMC Remedy Migrator goes over the tree from
top to bottom to find all the regular forms first (shaded forms). To make sure that the forms are
created in the correct order, all the regular forms are migrated first, then all the join forms.
Join form migration example
Before migrating the forms, BMC Remedy Migrator processes them as follows:
Retrieves Join Form A, and sees that it has two member forms: Join Form B and Join Form
C.
Retrieves Form B, sees that it is a join form, and adds it to the join form list.
Retrieves Join Form C, sees that it is a join form, and adds it to the join form list.
Looks at Join Form B and sees that it has two member forms: Regular Form D and Join
Form E.
Retrieves Regular Form D, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form D because it does not have any
members.
Retrieves Join Form E, sees that it is a join form, and adds it to the join form list.
Looks at Join Form E, sees that it has two members: Regular Form H and Regular Form I.
Retrieves Regular Form H, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form H because it does not have any
members.
Retrieves Regular Form I, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form I because it does not have any
members.
Looks at Join Form C and sees that it has two members: Regular Form F and Join Form G.

Retrieves Regular Form F, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form F because it does not have any
members.
Retrieves Join Form G, sees that it is a join form, and adds it to the join form list.
Looks at Join Form G and sees that it has two members: Regular Form I and Regular Form
J.
Retrieves Regular Form I and sees that it is a regular form. However, it has already been
added to the regular form list. At this point, all processing stops for Regular Form I because
it does not have any members.
Retrieves Regular Form J, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing for Regular Form J stops because it does not have any
members.
The forms are then migrated as follows:
Regular Forms D, H, I, F, and J are migrated first, because they do not depend on any other
forms.
Join Forms E and G are migrated next, because they are required for Join Forms B and C.
Join Forms B and C are migrated next, because they are required for Join Form A.
Finally, Join Form A is migrated, which was the original request.
Migrating a form and related objects

When migrating a form with related objects, BMC Remedy Migrator retrieves a list of the active
links, filters, escalations, associations, guides, applications, and web services attached to the form,
according to the options you set. It then adds those objects to the list of objects to be migrated.
For example, if you migrate a form with one active link and one filter, BMC Remedy Migrator
migrates the form, the active link, the filter, and any menus used by the form. If you migrate a join
form, BMC Remedy Migrator includes the objects related only to the join form. It does not include
the objects related to the forms needed to complete the join form migration.
BMC Remedy AR System and BMC Remedy Migrator use field IDs, not field names, to determine
differences between source and destination environments. For example, if the source form has a
field name of Field_ABC, and the destination form has a field name of Field_XYZ, with the same
field ID, BMC Remedy Migrator replaces instances of the form Field_XYZ with Field_ABC on the
destination server.
After a migration from a development server to a production server, you might notice that field
names on forms or fields referenced in workflow (such as Set Fields actions) have been changed
on the production server.
If field names are the same, but field IDs are not, and the migration includes data, then the
scenario is reversed: BMC Remedy Migrator migrates data to the destination form and creates
entries on the destination server where the field IDs are the same. If the source form has a field

name of Field_ABC and the target form has a field name of Field_ABC with different field IDs,
BMC Remedy Migrator migrates the data to the destination field ID that matches. If the field types
are not the same, the migration fails.
Before making modifications to your development environment, migrate the production server to
the development server. This ensures that field IDs are synchronized. If you need to add fields to
both environments manually, assign them the same field ID.
Archive forms
If you are migrating a form that has an archive form associated with it, the archive form is created
on the destination if it does not already exist, or it is modified if it already exists. When a regular
form is migrated for the first time, the server creates the form itself, then the archive form.
Migration modes
BMC Remedy Migrator executes migrations in two different modes: Migration mode and Scripting
mode. BMC Remedy Migrator defaults to the last mode used.
You can also use either Migration or Scripting mode to perform a copy/prefix migration on the
same server (see Copy-Prefix migrations (see page 2057)).
Depending on how many threads you allocate in the Migration option, you can perform as many
migrations simultaneously as there are threads. If BMC Remedy Migrator uses up its allocation of
threads, migrations are queued until a thread becomes available. For more information about
threads, see Using multiple-threads for multiple migration (see page ).
Migration mode
In Migration mode, migrations run immediately.
Scripting mode
In Scripting mode, you can create migration scripts that can be saved and run manually at your
convenience, or scheduled to run at a specific date and time.
You can use Scripting mode to migrate objects from one server to multiple servers. You can create
reusable sets of multiple server migrations and put them in a holding position. This keeps you from
having to run each migration separately, one after the other. You can schedule them to run on a
specific day and time, or you can open and run them whenever they are needed.
For additional information about migration scripts and scheduling migration scripts, see Creating
and saving migration scripts (see page ) and Scheduling scripted migrations (see page ).

Copy-Prefix migrations
When using only one server, you cannot migrate identically named objects to the same server. You
must change the prefix before a migration can begin. In a Copy/Prefix migration, you migrate
objects to the same server, and then change the object's prefix in the Prefix dialog box. See,
Migrating objects to the same server.
The Copy/Prefix migration runs in either migration or scripting mode. It is useful for doing simple
development or testing of workflow on the same server. It also keeps all the relationships between
forms and related workflow separate.
Managing embedded server names

Objects and fields you can migrate (see page 2059)

Sequence for migrating objects (see page 2060)
How preference servers work (see page 2061)
How authentication servers work (see page 2062)
BMC Remedy Migrator replaces all object references to the source server with the name of the
destination server when migrating from one server to another. When trying to determine if an
object references the source server, BMC Remedy Migrator uses the name of the server you
defined in the Accounts dialog box.
For example, if you define the server as a fully qualified host name (such as source.domain.com),
BMC Remedy Migrator uses source.domain.com as the name of the server it replaces. Any
references to the unqualified name source are not replaced. If you define the server name as only
source, BMC Remedy Migrator replaces any references it finds to both the unqualified name
source and the fully qualified host name source.domain.com. BMC Remedy Migrator considers
source.domain.com, source.some.otherdomain.com, and source.domain.net to be the same
server.
The following table outlines what happens to server references when BMC Remedy Migrator
replaces the reference for servers named "source" with the reference "destination," when both of
the servers are in the*domain.com* domain.
Change in server references for source names
Server name Server name Action taken by BMC Remedy Migrator

referenced replaced with
source destination recognizes source and replaces it with destination.
source.domain. destination recognizes source and replaces it with destination.

com
destination


source. recognizes source and replaces it with destination, because it does not know that the
otherdomain.net domain is not the correct one.
server.domain. server.domain. The object references a different server and BMC Remedy Migrator leaves the
com com reference intact.
The following table outlines what happens to server references when BMC Remedy Migrator
replaces the references for servers named source.domain.com with "destination," when both of
the servers are in the domain.com domain.
Changes in server references for destination names

source source does not recognize the name as the same as source.domain.com and does
not replace it.
source.domain.com destination recognizes source.domain.com and replaces it with destination.
source. source.otherdomain. does not recognize the name as the same as source.domain.com and does
otherdomain.net net not replace it.
server.domain.com server.domain.com The object references a different server and BMC Remedy Migrator leaves the
reference intact.
Objects and fields you can migrate

BMC Remedy Migrator can migrate the following BMC Remedy AR System objects and fields.
Objects
BMC Remedy AR System objects that you can migrate include:
Forms (including different views of forms)

Workflow objects (active links, filters, escalations, active link and filter guides), including
locked objects
Associations
Applications, including deployable applications
Packing lists
Web services
Menus
Groups
Roles
Distributed maps
Distributed pools
Data
Views
Flashboards (variables, data sources, Flashboards, and Flashboards alarms)

System objects
Plug-in definitions
Plug-in modules
Fields
BMC Remedy AR System fields that you can migrate include:
Data fields (character, diary, integer, real, selection, date/time, date, time, decimal,
attachment, attachment pool, currency)
Control fields (buttons, menus, toolbar icons)
Trim fields (lines, boxes, text)
Table fields (client side or server side), including tree view and table views
Page fields
Flashboards fields
Alert List fields
Application List fields
View fields
Result List fields
Data visualization fields
Sequence for migrating objects

BMC Remedy Migrator uses a predefined sequence for migrating objects. For Regular, Join,
Display-only, View, and Vendor forms, BMC Remedy Migrator looks for the views, then the fields,
for each form, repeating the process if necessary before it moves on to the next object type in the
sequence. The following table outlines the sequence of object migrations.
Object migration sequence
Sequence Object Sequence Object
1 Groups 15 Active link guides
2 Roles 16 Distributed Server Options: DSO

maps
3 Regular forms: 17 Distributed Server Options: DSO

pools
3a Views
3b Fields
4 Join forms: 18 Flashboards variables
4a Views
4b Fields
5 Display-only 19 Flashboards data sources

forms:

Sequence Object Sequence Object
5a Views
5b Fields
6 View forms: 20 Flashboards
6a Views
6b Fields
7 Vendor forms: 21 Flashboards alarms
7a Views
7b Fields
8 Fields 22 Filter guides
9 Views 23 Web Services
10 Images 24 Packing lists
11 Menus 25 Applications
12 Active Links 26 Plug-in modules
13 Filters 27 Plug-in definitions
14 Escalations 28 Data
How preference servers work

You can log on to a preference server, which sets the behavior and display characteristics of each
client. These preferences can be stored locally on the client machine, or centrally on a designated
preference server. Centralized preferences make the same settings and customizations available
when logging in to multiple machines. Local preferences can be used when no preference server is
designated or available. Regardless of whether centralized or local preferences are used, multiple
users can use the same client machine with individual preferences and customizations.
Only BMC Remedy AR System 5.0 or later servers can be used as preference servers. If no
preference forms are found on your AR System server, a text box appears asking if you want to
create the preference server forms. The BMC Remedy Migrator Preference form is then created to
set up a preference server.
For more information about preference servers, see Setting user preferences (see page 1344).
Note
If you are logged in to two computers simultaneously and make a change on one by
changing an option or licensing a server, you do not automatically see the new options or
licenses on the other computer. You must log on again to the preference server to view
the new changes.

How authentication servers work

Administrators can have greater control by verifying user authentication using an authentication
server . With an authentication server, BMC Remedy Migrator checks to see if a user is a
registered user. If a match is found, the user definition and permissions specified in the matching
user record are used. If no match is found, the authentication is stopped and the user is treated as
a guest user.
If authentication is not enabled in BMC Remedy AR System, BMC Remedy Migrator cannot
authenticate a user. See Configuring after installation (see page 241) or Configuring the AR
System server for external authentication (see page 260).
Cache file management overview

In this topic:
Refreshing and updating cached objects (see page 2062)

Space limitations on caching (see page 2063)
When you open a server window for the first time, BMC Remedy Migrator generates the following
cache files in the Migrator directory on your hard drive:
A server cache, where workflow support files are located.

A database information cache for the server, which lists all the required BMC Remedy AR
System object information. This information is used by the list views for both the server
windows and the form detail windows.
A dependency file cache for the server, which is used to generate upward and downward
dependency information.
You can specify the directory in which to store cache files. See Specifying directories to store
migration files (see page ).
Although initial caching takes time because BMC Remedy Migrator copies all the objects from the
server to your computer and builds the database, cache files ultimately save time and lessen the
load on the server.
Refreshing and updating cached objects

To recache your computer after the initial caching, select View > Refresh (or press F5).
Whenever you reopen a server window, BMC Remedy Migrator updates cache files, taking less
time because only changed objects are cached. BMC Remedy Migrator also updates the object
type cache when you switch object types in the left pane of the server window. For example, when
you go from Forms and click Filters, BMC Remedy Migrator updates filters. When you go from
Filters and click Forms, BMC Remedy Migrator updates forms.

BMC Remedy Migrator also updates the cache file during a migration. To view the changes in the
cache after a migration, refresh your display by pressing F5.
You can turn automatic caching on or off. To do so, select Tools > Options, and then click General
in the left pane to display the caching options (see Setting general options (see page )).
Note
BMC Remedy Migrator provides an option to keep or delete the database and
dependency files generated with .migrator files. See Setting general options (see page
).
Space limitations on caching

During a cache process, BMC Remedy Migrator warns you when less than 10 MB of space is
available on your computer. When you see this warning, stop the caching process, create more
hard drive space, and then cache again.
Warning
If you rename any object on a server where the cache is enabled, you must open that
server in BMC Remedy Migrator and update the cache before making any more changes
to that object. This is required for the cache to recognize the object changes.
Navigating the BMC Remedy Migrator interface

This section describes how to navigate the BMC Remedy Migrator interface. It also describes
logging on to AR System server through BMC Remedy Migrator.
Logging on to an AR System server using BMC Remedy Migrator (see page 2063)
Working with BMC Remedy Migrator (see page 2065)
Logging on to an AR System server using BMC Remedy Migrator

The first time you log on to an AR System server, BMC Remedy Migrator retrieves all object
definitions from the associated server. This retrieval builds a cache on the client machine in the
Migrator directory. The first retrieval can take some time, but makes it faster and easier to access
those definitions in the future.
Note

By default, caching is disabled. See Displaying objects in a server window (see page 2080)
for information about managing the cache process.
Logging on and opening a server window

BMC Remedy Migrator provides two methods by which you can log on. The following procedures
outline each method. For information about setting login options, see Setting general options (see
page ).
To log on to BMC Remedy Migrator
1. Perform either of the following actions:
If you are not already logged in, select File > New Server Window to display the Login
dialog box and open a new server window.
To log on to BMC Remedy Migrator without opening a server, select Tools > Login. For
example, you must be logged in to BMC Remedy Migrator to refresh a previously saved
differences report or to add licensed servers.
Note
You must license the server that you want to log on. For information about adding a
license, see Navigating the BMC Remedy Migrator interface (see page ).
1. In the Login dialog box, enter your BMC Remedy AR System user name and password for
that server, and click OK.
By default, the BMC Remedy Migrator login window shows the User Name and Password
fields only. By clicking the Options button, you can also display the Preference Server and
Authentication fields.
The first time you use BMC Remedy Migrator, both the User Name and Password fields are
empty. The next time you log on, BMC Remedy Migrator remembers the last user name and
tries that information first (unless it has been changed) when logging on to a server.
2. (optional) To log on to a preference server, click the Options button to display the
Preference Server field. Then, enter or select the preference server name.
3. If required, type your authentication server in the Authentication text box.
4. To add, modify, or delete an existing server or manage usage of a server, click the Accounts
button.
For information about the Accounts dialog box, see Working with BMC Remedy Migrator
(see page ).
5. Click OK.
6.
6. In the Select Server dialog box, select the server you want to use, and click OK.
The server window appears, showing the BMC Remedy AR System objects residing on the
server you logged in to. Then, the Retrieving Objects window appears and lists the objects
that BMC Remedy Migrator is opening for the server.
Note
Depending on the number of objects the server has stored, opening a server can
take some time while objects are being retrieved and cached. You can cancel the
cache process by clicking the Cancel button in the Retrieving Objects window.
7. (optional) To open another server window, repeat this procedure.

By logging on to each server individually, you can specify a different user name and
password for each server.
Working with BMC Remedy Migrator

This section describes viewing and using windows, and synchronizing views in BMC Remedy AR
System. It explains how to use the migration status pane and how to customize menus, toolbars,
and columns. It also describes how server windows work, how to display or remove objects and
forms in server windows, and how to export and convert definition and XML files.
BMC Remedy Migrator main window overview (see page 2065)

Using the migration status pane and tabs (see page 2067)
Using menus and the main menu bar (see page 2069)
Customizing BMC Remedy Migrator (see page 2076)
Working with server windows (see page 2078)
Creating a data search (see page 2093)
Using field mappings (see page 2095)
Shortcut keys (see page 2096)
BMC Remedy Migrator main window overview

The main BMC Remedy Migrator window displays tools and information that control viewing server
or report information and viewing synchronized objects across views. You can navigate in BMC
Remedy Migrator using the mouse or shortcut keys, or by customizing the main menu or toolbars.
For information about menus, toolbars, and shortcut keys, see Customizing BMC Remedy Migrator
(see page ). When you open BMC Remedy Migrator without logging on to a specific server, the
main window is empty. When you open a server window, you can display object details, migration
status details, reports, files, and scripts.
Note

Not all menu items or toolbar buttons are accessible until you log on to a server and open
a file.
BMC Remedy Migrator main window

The BMC Remedy Migrator main window includes the following areas:
Title bar--Displays the currently open server.

Main menu bar and toolbars--Appears at the top of the window. For information about
customizing the main menu bar and toolbars, see Customizing BMC Remedy Migrator (see
page ). For a detailed description of the main menu bar and toolbars, see Using menus
and the main menu bar (see page 2069).
Left pane (navigation pane)--Displays lists of objects available for the currently open server.
Object lists can be displayed in two formats:
Object type tab--groups objects in folders by how they are named. See Displaying
objects in the Object Type view (see page 2080).
Prefix tab--Lists objects by folders named according to how they are organized, for
example, a packing list. Some objects might be grouped under folders with labels
using initials. See Displaying objects in the Prefix view (see page 2080).
Right pane (object list view)--Displays the server and report windows, with details for the
currently selected object or report. See Types of object details (see page 2085).
Status bar--Appears at the bottom of the main BMC Remedy Migrator window. It displays
the following information:
Messages about the status of BMC Remedy Migrator tasks
The name of the user currently logged in to BMC Remedy Migrator

Help for menu commands and toolbar buttons
To show or hide the status bar, select View > Status Bar.
In addition, a migration status pane can be displayed at the bottom of the window
when you select View > Migration Status. This area displays migration in progress
and enables you to control, monitor, and store migrations. The status pane is
described in Using the migration status pane and tabs (see page ).
Viewing information in BMC Remedy Migrator windows (see page 2067)

Viewing synchronization within windows (see page 2067)
Viewing information in BMC Remedy Migrator windows

In the left pane of the server window, you can use either the Object Type or Prefix tab to select
Backup files, Script files, and Migration Report Result files. To view these files, save them in the
directories specified in BMC Remedy Migrator options. See Specifying directories to store
migration files (see page ).
To locate a file in a different directory, select Tools > Options > Directories. To display the contents
of a file, select that file in the right pane.
Object lists appear within windows in ascending order by name when you open a secondary
window or when you select a new object type.
Note
Nonalphabeti cal characters are sorted individually before alphabetical characters. For
example, a dash (-) is sorted before a colon (:).
Viewing synchronization within windows

To synchronize the window views, select an object in any open server or report window and select
View > Synchronize Views. If that object is located in the server or report, every open view displays
the selected object.
Using the migration status pane and tabs

You can use the migration status pane and status tabs to view and control migrations. From the
status pane, you can watch the progress of a migration and use the status tabs to monitor a
migration's status. You can also control active migrations and view information about active,
completed, and scripted migrations.
Migration status panes

The migration status pane at the bottom of the BMC Remedy Migrator window displays an instant
view for monitoring all your migration activity (see also Managing migrations (see page )).
To show or hide the migration status pane, select View > Migration Status.
Migration status pane
To undock and relocate the migration status pane, select the outer edge of the pane and drag it to
another location.
The following table outlines the information you can view in the migration status pane:
Information in migration status pane
Field What it does
Name Lists the script name or migration name.
Status Shows the status of an interrupted or completed migration, and how many passes of this migration have occurred.
For example, if this is the first instance of this migration, a migration is being repeated once, the message
"Migrating pass 1." This enables you to see how many times a specific migration occurred.
Type Designates a scheduled or immediate migration.
Progress Indicates the completion percentage for a migration.
Start Time Indicates the actual start time for a migration.
End Time Indicates the actual end time for a migration.
Source Lists the name of the source server.
Destination Lists the name of the destination server.
Description Displays a brief description of the migration.
Migration status tabs
The migration status tabs show you an instant view of all your migration activity. You can view
immediate, scheduled, or completed migrations, depending on which status tab you select.
Click each tab to show the status of the following types of migrations:

All--Shows all immediate and scheduled migrations in progress.

Immediate --Shows all immediate migrations that are in progress, queued, or interrupted.
Scheduled --Shows all scheduled migrations, as indicated by migration scripts.
Completed --Shows all completed migrations. To display the migration statistics in a
migration result report, click the Completed tab and then double-click a migration listing.
Using menus and the main menu bar

The main menu bar, at the top of the main BMC Remedy Migrator window, provides access to
most of BMC Remedy Migrator's features, such as: licensing and logging on to servers, migrating
AR System objects between servers, exporting definitions, and printing. You can customize BMC
Remedy Migrator's main menu to fit your individual working style. (See Customizing BMC Remedy
Migrator (see page ) for additional information.)
If a menu contains commands that are gray, that command is unavailable for the task you are
working on. Not all menu items are available or listed until you log on to a server and open a file. A
brief description of all of the main menu commands appears in the following tables.
File menu (see page 2069)

Edit menu (see page 2070)
View menu (see page 2071)
Servers menu (see page 2071)
AR System Objects menu (see page 2072)
Migrate menu (see page 2072)
Script menu (see page 2074)
Tools menu (see page 2074)
Window menu (see page 2075)
Help menu (see page 2075)
File menu
The selections available in the BMC Remedy Migrator File menu depend on the window that is
currently active. For example, the New Differences Object and New Migration Script selections
become available only when a server window is open and active. The Export to HTML selection
becomes available only when a dependencies, differences, or results report window is open and
active.
File menu selections
Menu Use to
selection
New Open a new server window. When you make this selection, you are prompted to select a server. You can have
Server multiple server windows open in a single session.
Window

Menu Use to
selection
New Create a new .migrator file. When you make this selection, a definition window opens. You can add to the contents
Migrator of this window by dragging objects to it from any open server window. Then, select either Server or Migrator File as
File the destination type.
New Create a new Differences report. When you make this selection, a new definition window opens. You can then add
Differences content by dragging objects to it from any open server window. Then, select either Server or Migrator File as the
Window destination type.
New Create a new migration script. When you make this selection, a new window opens. You can then record
Migration migrations that are happening from one server to another, or to a file.
Script
Open Select a file to open in BMC Remedy Migrator.
Close Close the active window.
Save Save an open window or file using the existing name or a default.
Save As Save an open window or file with a new name.
Print Select a printer, a print range (pages), and number of copies.
Print Preview the file you want to print (migration result, differences, and dependency reports only).
Preview
Print Setup Select a printer, paper, and orientation.
Send Open a send window form your email application so you can send the currently active file on your desktop.
Export to Export a report to HTML format for editing and printing. This selection appears only when a report is open.
HTML
Recent List the most recent files used.

Files
Exit Shut down BMC Remedy Migrator.
Edit menu
The following table lists selections in the BMC Remedy Migrator Edit menu.
Edit menu selections
Menu selection Use to
Copy Copy a selected object in a BMC Remedy Migrator window.
Paste Paste an object that was copied into a BMC Remedy Migrator
window.
Delete Delete a selected object in a BMC Remedy Migrator window.

View menu
The BMC Remedy Migrator View menu provides several submenus. The Search Bar command is
available only after opening a Form Details window; the Description Bar selection is available only
after opening a Script window; and the Zoom selection is available only when you are viewing an
active report.
View menu selections
By Application Filter the server view to show only local and deployable applications.
By Workspace Filter the server view to show only objects included in a specified workspace or packing list.
By Form Filter the current Server/Definition view to display a subset or selected list of forms, together with
related objects.
Normal Switch filtering off when users select viewing by form, application, or workspace.
Form Details Show form details in a new window, including fields, views, and related objects.
Differences Show the differences between two or more selected objects.
Form and Related Show the differences between forms and their related objects.
Differences
Downward Dependencies Show downward dependencies for a selected object.
Upward Dependencies Show upward dependencies for a selected object.
Toolbars Select the toolbars that you want displayed in the main window.
Migration Status Show or hide the migration status pane at the bottom of the main window.
Description Bar Show or hide the description bar (for before and after commands) when you are creating a migration
script.
Status Bar Show or hide the status bar beneath the migration status pane.
Arrange Icons Arrange a window's icons alphabetically by name, automatically, or lined up on a grid.
Zoom Set the Zoom factor for the dependencies, differences, and migration result reports, and for printing
a report.
Refresh Refresh the current view.
Synchronize Views Synchronize objects within the other open server and report windows.
Servers menu
The Servers menu is available only when a new script is created or an existing script is opened.
Servers menu selections
Change Login Information Update login information, or log on as a different user.
Add Server Select another server to add to the list of servers in a script.

Add Migration File Add a .migrator file.
Remove Server Remove a server from the list of servers in a script.
Change History Option Modify the Change History options on a server in a script.
Change History String Modify the string in the Change History options on a server in a script.
Default Prefix Options Change the default prefix options on a server in a script.
Use Definition Files for Specify a definition (.def ) file format as the backup on a server in a
Backup script.
Use Migrator Files for Backup Specify a .migrator file format as the backup on a server in a script.
Back Up All Objects Back up all objects on a server in a script.
Back Up Specified Objects Select the objects to be backed up on a server in a script.
Back Up Directory Specify a directory for storage of backup files on a server in a script.
AR System Objects menu

The Objects menu is available only when a new script is created or an existing script is opened.
Objects menu selections
Change Source Change the source server for an object in a script.
Change Change the destination server for an object in a script.

Destination
Prefix Options Change the prefix options for an object in a script.
Destination Name Change the name of the object on the destination server in a script.
Data Mode Open the Data Migration Settings dialog box used to set up data
migrations.
Number of Enter the number of records to use for a data migration.

Records
Search Criteria Enter an actual data migration search.
Remove Object Remove the object form the list of objects in a script.
Migrate menu
The following table outlines the Migrate menu and its submenus. The All Fields, All Views, and
Migrate Field by Type submenus and selections are available only from a Form Detail window.
Migrate menu selections
Migrate all objects.

All BMC Remedy AR System

Objects
Form and Related Objects Migrate selected forms and their related objects.
Deploy Application Migrate an application and its supporting objects.
Selected Objects Migrate selected objects.
Form Data Display a submenu that allows you to:
Migrate form data only.

Migrate a form and data.
Migrate a form, related objects, and data.
Migrate Objects by Type Display a submenu that allows you to migrate the following objects:
All forms
All active links
All filters
All escalations
All active link guides
All applications
All packing lists
All web services
All menus
All groups
All images
All distributed maps
All distributed pools
All Flashboards
All Flashboard data sources
All Flashboard variables
All Flashboard alarms
All Fields Migrate all fields form selected forms.
All Views Migrate all views from selected forms.
Migrate Field by Type Select the following field types to migrate from selected forms (from the Form Detail
window):
Character fields
Diary fields
Integer fields
Real fields
Selection fields
Date/time fields
Decimal fields
Buttons
Panel fields
Lines
Boxes
Text
Attachments
Tables
Alert fields
Result list fields
View fields

Flashboard fields
Currency fields
Date fields
Time fields
Set Admin Mode on Destination Turn on or off the restriction of non-administrative users during a migration.
Server
Migration Mode Run migrations immediately.
Scripting Mode Create a migration script to save or schedule.
Script menu
The following table lists selections available in the Migrator Script menu.
Script menu selections
Schedule Migration Schedule a migration for the specific month, date, and time, and the users to notify upon
Script completion.
Edit Scheduled Edit a scheduled migration.

Migration
Execute Migration Script Open and run a migration script.
Tools menu
The Tools menu includes Source Control options. If Source Control installed on your system, the
Source Control submenu selections are also available.
Tools menu selections
Login Open the Login dialog box.
Accounts Manage user and server lists (where you add servers to BMC Remedy Migrator)
Licenses Display current licenses and add or edit existing licenses.
Export Export object definitions to an BMC Remedy AR System definition (.def ) file.
Definitions
Export Export an application to an BMC Remedy AR System definition (.def ) or XML (.xml ) file.
Application
Export Locked Export locked object definitions to an BMC Remedy AR System definition (.def ) file. The lock key must be
Definitions entered and verified, and a lock type selected.
Convert Convert BMC Remedy Migrator definition (.def ) files to Migrator (.migrator ) definition format.
Definition Files
Customize Customize the main menu and toolbars.
Options Configure BMC Remedy Migrator options.

Source Control Display a submenu that allows you to perform the following tasks:
Get the latest version

Check in a file
Check out a file
Undo a checkout action
Add to Source Control
Remove from Source Control
Show the history
Show the differences
Show user information
Activate the refresh status
Run Source Control client
Window menu
The Window menu provides options for positioning BMC Remedy Migrator objects on your screen.
Window menu selections
Close Close the active window.
Close All Close all active windows.
Next Display the next active window.
Previous Display the previous active window.
Cascade Arrange windows so they overlap.
Tile Horizontally Arrange windows as horizontal, non-overlapping tiles.
Tile Vertically Arrange windows as vertical, non-overlapping tiles.
Arrange Icons Arrange icons at the bottom of the Window menu.
Server and Window List the open servers and windows for a session with the active server or window
List checked.
Help menu
The Help menu provides options for displaying BMC Remedy Migrator online help and version
information.
Help menu selections
Help topics Open BMC Remedy Migrator help.
About BMC Remedy Display program information, version number, and copyright
Migrator date.

Customizing BMC Remedy Migrator

You can customize the BMC Remedy Migrator main menu, toolbars, and columns in windows.
Customizing the main menu and toolbars
To rearrange the items on the main menu, drag the menu items to a new location on the menu. To
remove toolbar buttons from the main toolbar, drag the buttons down into the main window.
To change the look of the toolbars, create a new toolbar, or to change BMC Remedy Migrator's
default toolbars and main menu, use the following procedure:
To customize the main menu and toolbars
1. Select Tools > Customize.

2. In the Customize dialog box, perform any of the following actions in the Toolbars tab (the
following figure):
Click a toolbar name to select or clear that toolbar.
Click Show Tooltips to select or clear the help text that is displayed when you point to
a toolbar button.
Click Cool Look to select or clear the shadow effect around the toolbar buttons.
Click Reset to restore BMC Remedy Migrator's default toolbars and main menu.
Click New to create a new user-defined toolbar. Then, type in the new toolbar name
and click OK, making sure to select the Toolbars tab. The new toolbar appears on
your screen empty.
Customize dialog box-Toolbars tab

3. To add toolbar buttons or menu commands to the default view of the main window, click the
Command tab (the following figure) and select a category, and then drag the toolbar buttons
or menu items to your new toolbar.
Customize dialog box-Command tab

4. When you have finished making changes, click OK.
Rearranging window columns
You can rearrange the column order in a server window, a Form Detail view, and a Script view for
a chosen tree item.
To rearrange column order in a window
1. Select an object in the left pane of the server window.

2. Drag and drop the columns to a new location.
The next time you open the server window, BMC Remedy Migrator remembers your
changes and displays the columns in their new locations. You can also rearrange the
columns in the migration status pane.
Working with server windows

Use server windows to perform most migration tasks. When you open a server window, functions
in the main menu applicable to the task you are performing are available. Unavailable functions are
either not necessary for the task, or you have not selected the items that activate them.
You can have multiple server windows open in the BMC Remedy Migrator main window.
In this topic:

Opening a server window (see page 2079)

Displaying objects in a server window (see page 2080)
Viewing objects by form (see page 2081)
Viewing form details (see page 2082)
Viewing objects by application (see page 2083)
Viewing objects by workspace (see page 2084)
Types of object details (see page 2085)
Deleting objects from servers or files (see page 2092)
BMC Remedy Migrator performs the following actions:
Creates cache files by retrieving objects for the server and copying them to your computer.
A cache progress window shows the objects that are being retrieved. You can cancel the
cache by clicking the Cancel button.
Lists server objects in the left pane of the server window. You can select how objects are
viewed by clicking either the Object View or Prefix tabs.
Displays details for a selected object or report. You can view objects by form, by application,
or by workspace. See Displaying objects in a server window (see page 2080).
Opening a server window

Perform the following steps to open a server window in BMC Remedy Migrator.
To open a server window
1. Select File > New Server window.

2. From the list, select a server.
Opening a new server window

Displaying objects in a server window

When you log on to a server, the objects for that server are displayed in a server window.
Displaying objects in the Object Type view

The Object Type view lists objects by their type. It also lists backup, script, and result files. If no
objects exist on the server for an object type, that object type is not listed.
Object Type view
To view objects by type, click the Object Type tab in the left pane of the BMC Remedy Migrator
main window. To display all objects of a specific type, select the type from the list. The objects of
that type are listed in the right pane.
Displaying objects in the Prefix view
The Prefix view groups objects into folders, based on categories or on naming conventions you
define using colon (:) delimiters. For example, all objects named MB objectName appear in a folder
called MB. Objects named MB:Sub1: objectName appear in a Sub1 folder under the MB folder. In

the Name column, only the objectName portion of the object name is displayed.
Prefix view
To view objects by prefix, click the Prefix tab in the left pane of the BMC Remedy Migrator main
window. To view a set of objects, click the folder for the objects you want to view.
Viewing objects by form

You can view the list of objects associated with each form.
Viewing objects by form

To display objects by form
1. Select View > By Form.

The By Forms dialog box appears. By default, All Forms is the selected view option, and the
list of available forms is disabled.
2. In the View Option area, click the option button for the types of forms you want to view, and
click OK.
If you select Forms with Prefix, the Prefix field becomes enabled. Enter a prefix.
If you select Selected Forms, use the Add, Remove, Add All, or Remove All buttons
to create a list of the forms you want to view. To select more than one form, hold
down the Ctrl or Shift key as you make your selections.
3. In the left pane of the server window, click Forms to display the forms you selected.
BMC Remedy Migrator displays the forms according to the view options, and all the objects
related to those forms.
Viewing form details

You can double-click a form to view its details (or click once and press Enter).
In addition, you can view the details of forms (fields, views, and data) by right-clicking a form in the

right pane and then choosing Form Details. This action displays the Form Detail tree view.
Form detail list showing field details
To display the details of a selected form
1. In the left pane of the server window, under BMC Remedy AR System Objects, click Forms.
2. In the right pane of the server window, select a form.
3. Select View > Form Details.
The details for the selected form appear in the right pane of the BMC Remedy Migrator
window. The header bar shows the name of the form and the number of objects being
viewed for that form.
From the Form Detail window, you can migrate fields, views, data, and other objects related
to that form.
Note
When dragging an active link, filter, escalation, and so on from a Form Detail
window to another Form Detail window, the name of the form to which the object is
linked is not changed to the destination form name. Only fields and views are
created on the destination form. Also, data with fields and views are the only
objects migrated to the destination Form Detail view.
Viewing objects by application

You can view the list of objects pertaining to an application.

To view objects by application
1. Select View > View by Application.
View by Applications dialog box
2. In the By Application dialog box, select a local or deployable application.

For more information about local and deployable applications, see Deployable applications
(see page 2346).
The objects for the selected application are listed in the right pane of the server window.
Viewing objects by workspace

A workspace allows you to limit the objects displayed in a window to only those objects that are
associated with a particular packing list or application. When you create new objects in the context
of the workspace, the objects are added to the packing list or application. For more information
about workspaces, see Starting and logging on to BMC Remedy Developer Studio (see page 2255).
To view objects by workspace
1. Click in the server or file window whose workspace objects you want to display.
Make sure that All Forms is selected in the By Form dialog box; otherwise, the menu option
is disabled. See Viewing objects by form (see page 2081).
2. Select View > By Workspace.
The By Workspace dialog box appears. If no workspace has been created on this server,
the message "No current record" appears.
3. Select an application or packing list from the list, and click OK.
In the server window, the object category reflects the options selected in the By Workspace
dialog box. For more information about applications, see Developing an application (see
page 2242).

Types of object details

The right pane of the server or file window (the following figure) displays columns of objects and
details about each object listed. The following sections list the items listed for each object type.
Details for selected objects

Forms
The following table contains the items listed for forms.
Items listed for forms
Item Description
Form Name The name of the object.
Type For forms, the type of form, such as Join or Regular.
Access Point Whether an access point is available for the object. You can identify specific forms and guides in
deployable applications as access points, or points of integration, for use with other deployable
applications. For more information about deployable applications, see Deployable applications (see
page 2346).
New Entry Point Whether any new entry points are available for the object. A new entry point can be clicked to start a
task, such as creating a request. Entry points are listed in the Application List field on the home page.
For more information about home pages, see Home page components (see page 3155).
Search Entry Point Whether any search entry points are available for the object. A search entry point can be clicked to
start a search.
Owner The name of the user who created the object.
Timestamp The date and time on which the object was created or changed.
Last Changed The name of the user who last updated the object.
Lock State The locked state of the object. Locking allows application developers to protect workflow objects that
are not designed for or intended to be customized, by preventing them from being modified or even
viewed. An object can have one of the following locked states:
None — Allows users to view and modify the object.

Read-only — Prevents users from modifying the object, but allows them to view its details.

Hidden — More restrictive lock that prevents users from viewing details of a locked object,
including in BMC Remedy Migrator differences and dependency reports.
For more information about locked objects, see Locking objects (see page 3418).
Archive Whether archiving is enabled or disabled for a form. You can use the data archiving feature in BMC
Remedy AR System to set up options for backing up of data in forms. Archive forms can be migrated
if they exist on the destination. For more information about data archiving, see Archiving data (see
page 1895).
Views, Fields, Data The number of fields of each type included in the form.
Fields, Trim Fields,
Control Fields, Page
Fields, Table Fields
Member A, Member B, If this is a join form, the names of the member forms.
and so on
Active links, filters, and escalations

The following table contains the items listed for active links, filters, and escalations.
Items listed for active links, filters, and escalations
Item Description
Name The name of the active link, filter, or escalation.
Primary The name of the form that appears in BMC Remedy Mid Tier when the application opens.
Form
Forms The number of forms referenced.

Referenced
Enabled Whether this object is enabled.
Order The execution order for this object.
Execute On The action on which this object executes.
If Actions The number of if actions included.
Else The number of else actions included.

Actions
Owner The name of the user who created this object.
Timestamp The date and time on which this object was last changed.
Last The name of the user who last changed this object.
Changed
Lock State The locked state of the object. Locking allows application developers to protect workflow objects that are not
designed for or intended to be customized, by preventing them from being modified or even viewed. An object can
have one of the following locked states:

Typically a menu field or a button, which fires an active link when selected.

Control
Field (active
links only)
Focus Field A field on which an active link fires when the field gains focus.
(active links
only)
Qualification The text of any qualification created for this object.
Active link guides and filter guides

The following table contains the items listed for active links, filters, and escalations.
Items listed for active link guides and filter guides
Item Description
Name The name of the active link guide or filter guide that appears in the server window the BMC Remedy System
Form The name of the form to which the guide applies.

Name
Type The type of form to which the guide applies, for example, a regular form.
Label The name of the guide that appears in the Open dialog box in BMC Remedy Mid Tier.
Owner The name of the user who created the guide.
Timestamp The date and time on which the guide was last changed.
Last The name of the user who last changed the guide.
Changed

Hidden — More restrictive lock that prevents users from viewing details of a locked object, including in BMC
Remedy Migrator differences and dependency reports.
Description A description of the guide's function.
Applications
The following table contains the items listed for applications.
Items listed for applications
Item Description
Application The name for the application.

Name

Application The name for the application that appears in the Open dialog box in BMC Remedy Mid Tier, and in the application
Label title bar.
Primary The form that appears when the application is opened in BMC Remedy Mid Tier.
Form
Primary The view of the form that appears when the form is opened.
View
Owner The name of the user who created the application.
Timestamp The date and time on which the application was last changed.
Last The name of the user who last changed the application.
Changed

Application The current production state of the application, for example, Maintenance or Test.
State
Type The type of application, either local or deployable. Deployable applications use permissions based on roles that are
specific to the application, rather than groups that are specific to the server.
Description A description of what the application does or other pertinent information.
Packing lists
The following table contains the items listed for packing lists.
Items listed for packing lists
Item Description
Packing The name of the packing list.

List Name
Packing The label used, if any, for the packing list.

List Label
Owner The name of the user who created the packing list.
Timestamp The date and time on which the packing list was last changed.
Last The name of the user who last changed the packing list.
Changed


Description A description of the packing list's function.
Web Services
The following table contains the items listed for web services.
Items listed for web services
Item Description
Web The name of the web service.

Services
Name
Form The form used as the access for the web service.
Name
Web The name that is displayed to users.

Services
Label
Owner The name of the user who created the web service.
Timestamp The date and time on which the web service was last changed.
Last The name of the user who last changed the web service.
Changed

Description A description of the web service's function.
Menus
The following table contains the items listed for menus.
Items listed for menus
Item Description
Menu The name of the menu.

Name
Type The type of menu, either Character, File, Search, SQL, or Data Dictionary.
Refresh The condition on which the menu is refreshed, either On Connect, On Open, or on 15 Minute Interval.
Timestamp The date and time on which the menu was last changed.
Owner The name of the user who created the menu.
Last The date and time on which the menu was last changed.
Changed


Groups
The following table contains the items listed for groups.
Items listed for groups
Item Description
Group The unique ID for the group

ID
Group The name of the group.

Name
Group The permission type for the group, either None, View, or Change.
Type
Category The category of group, either Regular, Computed, or Dynamic.
Regular groups are explicit groups that you create and to which you assign a specific list of users.
Computed groups are explicit groups that you create and to which users are assigned based on a comparison
of users belonging to other explicit groups. For example, you can create a computed group that includes the
list of users who are members of both groups A and B, or members of group C, but not members of group D.
Dynamic groups use the contents of special fields to determine group membership.
For more information about groups, see Creating and managing groups (see page 1255).
Flashboard
The following table contains the items listed for Flashboards.
Items listed for Flashboards
Item Description
Flashboards A tool for representing data visually from BMC Remedy BMC Remedy AR System forms.
Flashboards Tools that enable sending of notifications to specific users based on a threshold value.
alarms
Flashboards Specify the information you want to monitor from a single form. In Flashboards, a variable represents data, such
variables as a slice of a pie graph, a bar in a bar graph, or a line in a line graph.
Plug-ins
The following table contains the items listed for plug-ins.
Items listed for plug-ins

Item Description
Plug-in The names of plug-in modules. Plug-in modules are used with the arplugin process, which is a companion process
modules to the AR System server. It loads configured plus-in modules to interface with external data.
Plug-in Definitions for selected plug-ins.

definitions
Roles
The following table contains the items listed for roles.
Items listed for roles
Item Description
Role ID The unique identifier for this role.
Role The name of the role.

Name
Application The application to which this role

belongs.
Images
The following table contains the items listed for images.
Item Description
Name The name of the image.
Type The type of the image. For example, jpeg, gif, png, etc.
Checksum This is short data which added to the image for the purpose of detecting errors which may be introduced during its
migration, transmission or storage.
Owner The name of the user who created the image.
Timestamp The date and time on which the image was created or changed.
Last The name of the user who last updated the image.
Changed
Description A description about the image.
Lock State The locked state of the image. Locking allows application developers to protect workflow objects that are not
designed for or intended to be customized, by preventing them from being modified or even viewed. An image can

Hidden — More restrictive lock that prevents users from viewing details of a locked object, including in BMC
Remedy Migrator differences and dependency reports.
Associations
The following table contains the items listed for associations.

Item Description
Name The name of the association.
Enabled Whether this object is enabled.
Type The type of association. There are two types of associations which you can create in BMC Remedy
Developer Studio:
Direct associations
Indirect associations
For more information, see Associations overview (see page 117).
Primary Schema The name of the primary form used in the association.
Secondary The name of the secondary form used in the association.

Schema
Owner The name of the user who created the association.
Timestamp The date and time on which the association was created or changed.
Last Changed The name of the user who last updated the association.
Deleting objects from servers or files

Although you typically delete objects from within Developer Studio before you migrate, you can
delete objects, including locked objects, from servers or files using BMC Remedy Migrator. To
make sure that nothing is affected by the deletion, BMC Remedy Migrator runs a check on the
object that you want to delete.
Note
Locked objects can be deleted only in blocks. Deleting one object that belongs to a
locked group deletes the entire group. Deleting a locked form that is part of a join deletes
the join form.
To delete objects
1. In the right pane of the server or file window, select the objects you want to delete.
BMC Remedy Migrator cannot delete DSO (Distributed Server Option) Map-related forms,
User and Group forms, and BMC Remedy AR System-specific forms, such as the User
Preference form. Also, BMC Remedy Migrator does not support deletion of data in .migrator
forms.
2.

If other objects are affected by the deletion, those objects are listed. If no other objects are
affected, a confirmation message appears.
Deleting objects — impact warning message
3. Confirm that you want to delete the objects:
Click Yes to delete the specified selection and continue to the next object.
Click No to skip the specified selection.
Click Yes to All to delete all the selected objects.
Click No to All to stop the deletion.
Warning
If you select Yes to All, BMC Remedy Migrator deletes every object without checking the
impact of the deletion on the links to other objects.
Creating a data search

A BMC Remedy Migrator search allows you to create specific search criteria of your data records
for a customized migration.
Note

This option is not available if the source is a file.
To create a data search
1. In the Data Migration Settings dialog box under Data Settings, select Search Selection from
the Data Mode list box.
If you supply a number in the Number of Entries text box, only the first number of entries
that match the search are migrated.
2. To create a search, click the list box next to the Search Criteria text box.
Search Criteria dialog box
3. In the Search Criteria dialog box, enter search criteria. Use the following methods to help
build a search:
Click Fields to display a menu for fields, selection values, and keywords.
Select Fields, Selection Values, or Keywords to display submenus with variables that
are specific to the data records you are migrating.
Important
Because BMC Remedy Migrator relies on the API to generate qualification

structures, BMC Remedy Migrator does not support using locale-specific
formatting in qualification strings. The API supports generic formatting such
as dd-mm-yy for dates and number formats without punctuation (such as
15000 instead of 15,000 ). Because of this, do not use spaces, comma-
separated values, or any other locale-specific punctuation when entering
qualifications in BMC Remedy Migrator. For example, when entering a
keyword, be sure that there are no spaces. An entry such as*$
TIMESTAMP$* (with a space between the $ and the T ) causes an error.
Here are some examples of searches you can create:
'Creator' = "Administrator" AND 'License Type' = "Fixed"
In this example, BMC Remedy Migrator searches for entries created by an

administrator user with a fixed license.

'Creator' = "Jane Doe"
In this example, BMC Remedy Migrator searches for entries created by the user Jane
Doe.
4. Click OK to use the search, or Cancel to stop it.
Your search criteria appear in the Search Criteria field of the Data Migration Settings dialog
box.
Search criteria for data migration
Using field mappings

The Enable Field Mapping option in the Data Migration Settings dialog box allows you to apply field
mappings to a data migration. When you check the Enable Field Mappings check box, the
Mappings button becomes active. Using this feature, you can map source fields to either a
destination field or a keyword.
You can also save mappings to a file for reuse later, to save time and reduce errors. You can load
the saved mapping file instead of entering the mapping values again. When you save a mapping,
the form name, the server the form resides on, and the data file name are saved.
You can auto-map all fields according to the field ID or the field name used in Developer Studio .
You can remove any of these generated mappings or add mappings.
Keep these conditions in mind when using field mappings:
Field mapping in BMC Remedy Migrator does not work with data files such as .arx files.
BMC Remedy Migrator does not perform any validations on field mappings.
A source field can be mapped only once.
A destination field can be mapped to more than one source field.
To apply field mappings
1. Check the Enable Field Mappings box in the Data Migration Options dialog box.
2. Click the Mappings button.
3. In the Field Mappings dialog box, enter the mappings you want to use for the data migration.
To auto-map field IDs or field names, click the Auto Map IDs or Auto Map Names
buttons.

3.
To add a mapping, click Add Mapping.

To delete one or more mappings from the Current Mappings list, select the
mappings, and click Delete. To remove all of the mappings, click Delete All.
To save a mapping, select the mapping and click Save.
To load a mapping you have saved, click Load and select the mapping.
4. Click OK.
Shortcut keys
BMC Remedy Migrator uses special shortcut keys for menu commands and when working in a
server window using the Migrate and Tools menus.
Shortcut keys
Menu Key sequence Use to
File menu Ctrl+N Open a new server window.
Ctrl+F Create a new*.migrator* file.
Ctrl+R Create a new differences window into which you can drag and drop
content.
Ctrl+O Open an existing file or browser window.
Ctrl+P Print the active document.
Ctrl+S Save the active file.
Edit menu Ctrl+C Copy a selection and put it on the clipboard.
Del Delete selected objects form a server or file.
Ctrl+V Paste a selection from the clipboard and put it in an active file.
Migrate Ctrl+M Migrate selected objects.

menu
Tools menu Ctrl+D Show differences.
Ctrl+E Show downward dependencies.
Ctrl+U Show upward dependencies.
All F5 Refresh the display.
Ctrl+A Select all choices in Form Detail and Server views.
Setting BMC Remedy Migrator options

BMC Remedy Migrator provides various categories of options that enable you to configure how to
process object and data migrations, how to manage differences between source and destination,
how to display migration results, and the directories to use for backup, result, script, and cache

files. The following sections describe each option category.
You can reset any options you have changed back to their default values by clicking the Set
Default button for that set of options.
Setting general options (see page 2097)

Migration options (see page 2098)
Specifying directories to store migration files (see page 2115)
Viewing backup, script, and results files (see page 2116)
Working with Source Control (see page 2116)
Setting general options

Use the General options to change when login prompts occur, when cache refreshes happen, and
whether confirmation prompts should be displayed when performing migrations.
To reset options to their default values, click Set Default.
General options

To select general options
1. Select Tools > Options.

The BMC Remedy Migrator Options dialog box appears.
2. In the BMC Remedy Migrator Options dialog box, select General.
3. Select the following general options:
Login/Display Login Dialog Box for Each Server Connection — If unchecked, enables
you to log on to multiple servers using a single password. If checked, you must log on
every time you open a server window or whenever a server is referenced. You can
use this option to specify account settings to limit available servers. See Setting-up
BMC Remedy Migrator (see page 652).
Caching — Allows you to cache the local server or update directly from the server.
Refresh object cache and database on type change — If checked, refreshes
objects when changing to a different object type (for example, from active links
to filters). Objects in BMC Remedy Migrator are also refreshed when you open
a server and when you press F5 to refresh manually.
Cache server objects locally — If checked, refreshes objects locally.
Delete associated dependency and database files for .migrator binary files
when the BMC Remedy Migrator file is closed — Provides the option to keep
or delete the database and dependency files that are generated with*.
migrator* binary files. Earlier, these files were always deleted when a .migrator
file was closed, requiring them to be regenerated each time a .migrator file
was reopened. This process can consume up to 40 minutes for the largest*.
migrator* files.
Retaining the database and dependency files eliminates the recaching
process and allows .migrator files to be reopened faster. Because the files
are retained, this option requires additional space on the server where the .
migrator files are stored.
The default value is not to delete the files (option unchecked).
Migration Mode — If checked, confirmation prompts are displayed when
performing migrations in Migration mode, or when migrating data entries to the
same form.
4. Click OK.
Migration options
Migration options set how migrations are performed.
Migration options

You can select the following migration options:
Multiple-thread — Specifies options for using multiple threads during migrations.

Required Objects — Specifies whether to migrate required menus, table field forms, join
form members, associations, applications, BMC Remedy Flashboards variable and data
source objects, and forms related to menus and associations.
Backup — Specifies which types of objects you want to back up, where to back them up,
and the type of file to back them up as.
Object Removal — Provides options for deleting or disabling objects that reside on the
destination server, but not on the source server, during a Form and Related Objects
migration.
Change History--Specifies how BMC Remedy Migrator adds or merges entries in history
fields after each migration.
Groups — Specifies how BMC Remedy Migrator merges new groups with existing groups.
Data — S pecifies default settings for data migrations. These settings are used as the
default settings in the BMC Remedy Migrator Data Settings dialog box.
Retry — Enables you to specify the number of migration retries and the time (in seconds)
between retries. The default number of retries is 3, and the default number of seconds is
300.
Ignore Prefixes — Enables to you specify prefixes that should be ignored during migrations.

Masks — Enables you to include or exclude objects in a migration or a Differences report.

You can synchronize mask settings so that they are the same for both migrations and
Differences reports.
For each group of options, you can revert to the BMC Remedy Migrator defaults by clicking Set
Default.
Selecting objects to migrate (see page 2100)

Using multiple-threads for multiple migration (see page 2102)
Backing up destination server (see page 2103)
Removing or disabling objects (see page 2105)
Setting the change history options (see page 2107)
Merging groups (see page 2109)
Merging data (see page 2110)
Setting migration retry options (see page 2112)
Specifying prefixes to ignore (see page 2113)
Specifying objects to compare (see page 2114)
Selecting objects to migrate

Under Required Object settings, you can specify objects to be migrated automatically. These
options guarantee that all required objects are included in a migration.
With Shared Workflow Settings, you can either merge the list of forms linked to shared workflow
objects on the source server with the list of forms on the destination server, or replace the list of
associated forms on the destination server with the list on the source server.
To select Required Object options

2. In the BMC Remedy Migrator Options dialog box, select Migration > Required Objects.
Required Objects options

3. Leave the option settings for the following objects at their default values of Yes to have them
migrated automatically:
Menus
Table field forms
Join form members
BMC Remedy Flashboards variables
Flashboard data sources
Associations
Forms related to menus
Forms required by applications
Forms related to associations
4. To require migration of forms required by applications, select Yes for the Migrate Forms
Required by Applications option. If you are migrating data for a form that the application
does not own, the Yes setting ensures that the required form for the data is migrated to the
destination. If this option is set to No and you are migrating data for a form that the
application does not own, BMC Remedy Migrator creates a special data-only form as a
placeholder for the data so that it can be migrated successfully. See Migrating applications
(see page ).
5. To require migration of the state of an application, select Yes for Migrate Application States.
This property defines the application state (Maintenance, Production, or Test). It applies to
deployable applications only. For more information about application states, see Working
with deployable application states (see page 2356).

6. Select Yes or No for Merge Shared Workflow, depending on how you want to handle shared
workflow objects:
Yes — The list of s hared workflow forms associated with the object on the source
server mergeswith the list of shared workflow forms on the destination object.
No (default) — The list of shared workflow forms associated with the object on the
source server replaces the list of shared workflow forms on the destination object.
7. Click OK.
Using multiple-threads for multiple migration

Using the Multiple-thread options, you can select whether to use multiple threads for multiple
migrations. The term thread refers to operating system functionality, allowing programs to break up
into two or more independent work units for concurrent execution. Multiple threads allow the
execution of other tasks while a migration is in progress, or to do multiple migrations concurrently.
If you do not use multiple threads, you can run only one migration at a time. The default setting is
multiple threads and execution of up to 10 migrations at a time. The optimal number of migrations
to select depends on your hardware configuration.
For more information about working with threads, see AR System server threads (see page 156).
To select Multiple-thread options

2. Under Category, open the Migration list and select Multiple-thread.
Multiple-thread options

3. Select Use Multiple Threads for Migrations to execute more than one migration at a time;
select Do Not Use Multiple Threads for Migrations to limit migrations to one at a time.
4. Enter the number of migrations you want BMC Remedy Migrator to execute.
If you execute more migrations than the threads you have specified, the extra migrations are
queued until a thread becomes available.
5. Click OK.
6. Restart your computer for the multi-thread option changes to take effect.
Backing up destination server

Backup options enable you to back up the destination server before a migration occurs. As a
safeguard, BMC Remedy Migrator copies the objects to be changed on the destination server to a
backup directory before migration by default. (Only destination servers are backed up.)
You can view backup files from a server or file window by selecting Backup Files in the left pane
and viewing the files in the right pane.
Note
BMC Remedy Migrator does not back up data for restored fields. Also, BMC Remedy
Migrator does not support backups of BMC Remedy Flashboards or plug-ins to definition (
.def ) files. These objects can be backed up using . migrator files.

To select Backup options

2. Under Category, select Migration > Backup.
Backup options
3. In the Backup the following objects area, select a backup option:

Back up all objects (default) — all objects are backed up.
Back up specified objects — A list of objects appears. The default selection is Yes for
each object. If you do not want to back up an object, click the object name and select
No from the drop-down list for that object.
Disable all — BMC Remedy Migrator does not perform any backups.
4. In the Backup Root Directory section, select a location to store your backup files, or accept
the default BMC Remedy Migrator backup directory shown.
By using the BMC Remedy Migrator backup directory, you can access backup files
conveniently by clicking Backup Files in the left pane of the server window.
5. In the Backup File Type region, select the type of file you want your objects backed up as.
Note
Make sure you have enough space on your computer for the backup files.

Select a file format:

Migrator (*.migrator ) — default setting
Definition (*.def )
Both Migrator files and definition (*.migrator and *.def )
6. Click OK.
Removing or disabling objects

Object Removal options enable you to delete or disable objects from a Form and Related
migration.
Objects that can be disabled:
Active links
Escalations
Filters
Objects that can be deleted:
Active links
Escalations
Filters
Filter guides
Active link guides
Web services
BMC Remedy Migrator deletes or disables objects only on the destination server as part of a
Forms and Related migration. For example, if you migrate Form 1 from Server A to Server B, BMC
Remedy Migrator deletes or disables Active Link x and Filter x from Server B.
Note
Object Removal options do not apply to locked workflow.
Migration object removal example

During a Forms and Related Objects migration, any objects related to a form that exist on the
destination but not on the source can be deleted, disabled, or ignored on the destination when the
migration takes place. If you specify that objects on the source should be deleted, BMC Remedy
Migrator backs up those objects before deleting them (see Backing up destination server (see
page )).
Note
Forms are never deleted during migrations.
The default setting for these options is to disable all objects.
To select Object Removal options

2. Under Category, select Migration > Object Removal.
Object Removal options

3. In the Delete or Disable Objects section, select how BMC Remedy Migrator should handle
objects on the destination during a Form and Related Objects migration:
Ignore All Objects — BMC Remedy Migrator ignores all objects on the destination
server.
Disable All Objects (default) — BMC Remedy Migrator disables all objects. The
objects remain on the server disabled.
Disable Specified Objects —
When Disable Objects is selected, BMC Remedy Migrator disables the active
links, escalations, or filters related to the selected objects.
When Delete Objects is selected, BMC Remedy Migrator deletes the active
links, escalations, filters, filter guides, active link guides and web services
related to the selected objects.
4. Click OK.
Setting the change history options

With the Change History options, you can modify, merge, or append an BMC Remedy AR System
Change History. The change history of an object includes the owner of the object, who last
modified it, and the date it was modified.
Note

Change History merging works only when the difference mask for the workflow property is
enabled in the Options dialog box, and when the change history options have also been
configured.
To select Change History options

2. Select Migration > Change History.
3. In the Change History Merge Options area (the following figure), select how BMC Remedy
Migrator should merge or add entries to the change history after each migration:
Do not modify Change History (default)--the existing change history on the source is
not migrated to the destination.
Merge Change History
Append string to Change History--enables you to enter some text, such as a
description of the change history.
Merge Change History and append a string--the String field becomes enabled, and
you can enter some text, such as a description of the merge.
4. Click OK.
Change History options

Merging groups
Group options enable you to select how BMC Remedy Migrator should merge new groups with
existing groups. BMC Remedy AR System defines several special groups that cannot be created
using the Group option, including public, administrator, subadministrator, customize, submitter,
assignee, and assignee group.
Note
Groups are migrated by group ID, not by group name.
To select Group options

2. Under Category, select Migration > Groups.
3. In the Group Merging options area (the following figure), select how BMC Remedy Migrator
should merge new groups with existing groups:
Reject Duplicate Groups — BMC Remedy Migrator generates an error for groups
with existing request IDs.
Generate New ID for All Groups — BMC Remedy Migrator creates a new request ID
for all groups.
Replace Old Group with New Group — BMC Remedy Migrator replaces old group
information with new group information.
Update Old Group with New Group's Data — BMC Remedy Migrator merges old
group information with new group information.
Group options

4. For each group merging option, select either or both settings:

Ignore Required Fields
Ignore Pattern Checking
5. Click OK.
Merging data
Data options enable you to select how BMC Remedy Migrator should merge new data with existing
data. "Data" is defined as the entries within forms.
To select Data options

2. Select Migration > Data.
3. In the Data Merging options area (the following figure), select how BMC Remedy Migrator
should merge new data with existing data:
Reject Duplicate Records — BMC Remedy Migrator generates an error for records
with existing request IDs.
Generate New ID for All Records — BMC Remedy Migrator creates a new request
ID for all records.
Note
This option is not supported for migrations in which the destination is a file.

Replace Old Record with New Record — BMC Remedy Migrator replaces old
record information with new record information.
Update Old Record with New Record's Data — BMC Remedy Migrator merges old
record information with new record information.
Data options
4. For each data merging option, select one or both settings:

Ignore Required Fields
Ignore Pattern Checking
5. In the Default Data Migration Mode section, select which data records to migrate:
Do not migrate any records.
Migrate all records.
Migrate query selection.
Migrate first numberOfRecords records.
6. Click OK.
Note
The Related Workflow options section is available only when the destination is a server;
not available if the destination is a migrator file.

Setting migration retry options

Retry options enable you to specify if BMC Remedy Migrator should stop a migration and attempt
recovery if the server crashes, is stopped by another user, or becomes too busy to return results.
Earlier, BMC Remedy Migrator would continue to migrate all objects even when the server stopped
functioning.
You can also specify the number of retries and the time (in seconds) between retries. The default
number of tries is 3, and the default wait time is 300 seconds.
To set retry options

2. Select Migration > Retry Options.
3. In the Number of Times to Retry (the following figure), enter a number, or accept the default
value of 3. If you want no retries, enter 0.
4. In the Seconds to Wait Between Retries, enter a number, or accept the default of 300
seconds.
5. Click OK.
Retry options

Specifying prefixes to ignore

This option enables you to instruct BMC Remedy Migrator to bypass workflow objects that begin
with specific prefixes during a direct or a scripted migration.
All BMC Remedy Migrator installations include a default list of prefixes in the Ignore Prefixes dialog
box. You can add new prefix names, edit existing prefix names, or clear the list. A Set Defaults
button is available to restore the default prefix list at any time.
The default prefixes include those required to allow correct migration of CMDB, BMC Remedy
Approval Server, and SLA/SLM applications. They are:
AP
OBJSTR
RE
BMC
SLA
zSLAGen
Ignore Prefix can be applied to all workflow objects except these:
Data
Roles
Groups and Computed Groups
Fields
Views
Prefixes ignored in Results report
When a migration is completed, the Results report lists the prefixes that were ignored. The status
information for workflow objects ignored during a migration notes these objects as ignored.
To specify prefixes to be ignored

2. Select Migration > Ignore Prefix (the following figure).
3. Perform any of the following actions:
To add a prefix to the list, click Add, and enter the prefix name.
To remove a prefix from the list, select the prefix, and click Remove.
To edit the name of an existing prefix, select the prefix from the list, click Edit, and
make the needed changes.
4. Click OK.
Ignore Prefix option

Specifying objects to compare

Migration mask options enable you to specify exactly which objects to compare between source
and destination before a migration and what should be migrated if an object already exists.
You can also synchronize migration mask options with the mask options for Differences reports, so
that the settings are the same for both types of options. The Synchronize button provides a
convenient way to create an exact match between the migration and Differences report mask
options.
To set migration mask options
1. Select Tools > Options, and select Migration.

2. Select Masks.
3. Click in the field for the type of object for which you want to set options (the following figure),
and select the option from the drop-down list.
4. To synchronize the migration mask options with those for the Differences report, click
Synchronize Difference Masks.
For more information about Differences report mask options, see Mask options (see page
).
5. Click OK.

Migration mask options
Specifying directories to store migration files

Directory options enable you to specify the directories in which backup, migration result, script, and
cache files are stored. Even when the directory path or name is changed, BMC Remedy Migrator
locates all the appropriate files for a specific server.
To select directory options

2. Under Categories, select Directories.
When you are using BMC Remedy Migrator for the first time, the default directory paths are
shown. You can keep these default selections, or change them.
3. To change the directory path for a file type, click the button to the right of the directory path
field, and enter a new path.
4. Click OK.

Viewing backup, script, and results files

You can view the BMC Remedy Migrator files on different servers regardless of the directory
options setting.
To view your files
1. Click the server window associated with the backup, result, or script file you want to view.
2. In the left pane of either the Object Type or Prefix view, click either Backup Files, Script
Files, or Result Files.
Viewing backup, script, or result files
The files are listed in the right pane. For each file, the list shows the name (including the date and
time of the migration) and the migration status.
To open a file, double-click the file name.
Working with Source Control

BMC Remedy Migrator Source Control (SC) functions in the same way that the BMC Remedy AR
System SC functions, except that BMC Remedy Migrator can generate differences reports
between objects under SC. If SC is enabled BMC Remedy AR System (Enforced mode enabled),
BMC Remedy Migrator can also enable SC. See Configuring AR System servers (see page 255)
and Setting version control options (see page 263).
Note
You can use Source Control with BMC Remedy Migrator only when the AR System
server is integrated with a third party source control system, by using the BMC Remedy
Administrator tool.

SC is a standard that was developed for tools to interface to Source Control systems (such as
Microsoft Visual SourceSafe, PVCS, CM Synergy, and so on). BMC Remedy Migrator provides an
interface to the SC system so it can "talk" to these tools. This allows you to save your work with
version numbers and checkin and checkout capability. The checkin and checkout capability lets
teams share an application without overwriting each other's work.
In this topic:
Starting SC in BMC Remedy Migrator (see page 2117)

To start and use SC in BMC Remedy Migrator (see page 2118)
Using SC in BMC Remedy Migrator (see page 2118)
BMC Remedy Migrator migrates an object and replaces it within the Source Control system if:
The object is checked in to SC.

The object is checked out by the same user who is performing the migration.
If the object is checked out by a user other than the user who is performing the migration, the
object is not migrated.
Because SC migration is multi-byte, all Unicode items are converted to multi-byte and back when
working with SC.
Starting SC in BMC Remedy Migrator

SC integration in BMC Remedy Migrator is essentially the same as that in BMC Remedy AR
System. The one exception is that BMC Remedy Migrator can compare the differences between
SC objects using the BMC Remedy Migrator differences report.
BMC Remedy Migrator SC Options

To generate a differences report for SC, select Tools > Source Control > Show Differences. For
information about working with differences reports, see Migrating applications and data between
AR System servers (see page )
Note
Groups, Data, DSO Maps, Fields, and Views cannot be added to SC.
To start and use SC in BMC Remedy Migrator
1. Verify that you have SC enabled BMC Remedy AR System for a particular server by viewing
the server window to see if SC columns are displayed.
2. Select Tools > Source Control to display the BMC Remedy Migrator SC options, or use the
Source Control toolbar.
Using SC in BMC Remedy Migrator

The BMC Remedy Migrator SC menu and toolbar buttons enable you to perform standard SC
functions. You can also check out objects, convert them from a*.def* file to a .migrator file, and
generate a differences report. The SC login box requests your name and password only when you
log on for the first time.
To verify that BMC Remedy Migrator integrates to your Source Control systems application, view a
window within BMC Remedy Migrator. If SC is functioning, the following columns appear in the
BMC Remedy Migrator Server, Form Detail, and Script windows.
Source control information in BMC Remedy Migrator windows
Column heading Description
In SC Verifies if the object is in SC. This heading only appears in a SC

window.
Checked Out By States who has the object checked out.

User
SC Last Modified By States who last modified the object.
SC Timestamp States when an object was last accessed.
If you see a check mark over an object's icon, that object has been checked out. BMC Remedy
Migrator remembers column settings for the next viewing (see Rearranging window columns (see
page 2078)).

The following table lists and describes the functions available from the BMC Remedy Migrator SC
toolbar.
Source control icons in BMC Remedy Migrator SC toolbar
BMC Description
Remedy
Migrator
SC icon
Get Latest Retrieves the latest definition file for the object being checked into SC and imports it to a server. When you "get" an
Version object, you are retrieving a copy. The file is not locked from other system administrators.
Check In Checks the file back into SC. If Enforced mode is enabled in BMC Remedy AR System and you check in an object,
the file is no longer locked and other system administrators can use it or modify it. If Enforced mode is disabled,
more than one user can check in an object at the same time.
Check Out Checks a file out of SC. If Enforced mode is enabled in BMC Remedy AR System and you check out an object, the
file is locked and no other system administrator can modify it. If Enforced mode is disabled, more than one user can
check out an object at the same time.
Undo Overrides objects that have been checked out by someone else. You must have a working folder set in your SC
Check Out client for this command to work properly. The file is no longer locked and the earlier version is retained in the SC
project.
Add to Adds the objects to the SC database. The file is archived in the SC project.
Source
Control
Remove Removes the objects from SC.

from
Source
Control Note
Removing files from SC does not remove them from the server.
Show Shows the history of objects selected in the SC integration. History reports summarize information about revisions
History of the objects.

Show Checks out objects, converts them to a .migrator file, and generates a differences report. See Migrating
Differences applications and data between AR System servers (see page )
User Displays user information about administrators of the SC database.

Information
Refresh Refreshes the current status information of an object from the SC database.
Status
Run Runs the SC system client.

Source
Control
Client
Performing migrations
BMC Remedy Migrator is fully Unicode capable. BMC Remedy Migrator allows migration of objects
and data between non-Unicode and Unicode servers. BMC Remedy Migrator does not have to be
executed on the same locale as a non-Unicode server.
Definition (.def ) files with multiple character encodings can be migrated as long as each block
within the .def file contains the character encoding used at the beginning of the block. If that line is
missing, the migration must be executed on a server of the same locale that was used to create
the .def file.
This section describes how to migrate objects, fields, and data. It also includes procedures on how
to run and clear migrations, and how to perform Copy/Prefix migrations.
Migration checklist (see page 2121)

Managing migrations (see page 2121)
Migrating objects between servers or files (see page 2122)
Migrating applications (see page 2123)

Migrating a form view and its associated fields (see page 2126)
Migrating fields (see page 2128)
Migrating data (see page 2129)
Migrating objects to the same server (see page 2135)
Migrating differing objects (see page 2136)
Migrating dependent objects from a Dependency report (see page 2137)
Migrating overlay objects and custom objects (see page 2137)
Migrating using command-line interface (see page 2146)
Migration checklist
Before you begin a migration, verify the following information:
Are you licensed and logged on to all of the servers you want to migrate to and from?
See Migrating applications and data between AR System servers (see page ) for more
information.
Do you want to restrict users from accessing a destination server that is involved in a
migration? (In BMC Remedy Migrator, Administrator mode is set to*on* by default.) If yes:
Select the production server window and select the Migrate menu.
Select Set Admin Mode on Destination Server to turn it on (check) and select it again
to turn it off (uncheck). If Set Admin Mode on the destination server is selected, BMC
Remedy Migrator enables the Administrator-Only mode on the destination server (if
your server supports it) during a migration, and turns it off when the migration is
complete.
Did you set up your migration and report options in the Tools menu? See Setting BMC
Remedy Migrator options (see page 2096) for setting up migration options and Chapters 8
through 10 for setting up report options.
If Enforced mode is enabled on the destination server, are all the objects on the
destination server checked into Source Control? BMC Remedy Migrator does not
change objects on a destination server if Enforced mode is enabled in BMC Remedy AR
System and the object is checked out by another user. For more information about the use
of source control in BMC Remedy AR System, see Setting version control options (see page
263).
Do you want to review object dependencies or view object differences before you
start migrating? See Migrating applications and data between AR System servers (see
page ) and Migrating applications and data between AR System servers (see page )
Have you verified or added any prefixes for workflow items that should be ignored
during the migration process? See Setting BMC Remedy Migrator options (see page 2096)
.
Managing migrations
Use the migration status pane to view active or completed migrations, and monitor and control
migration activity. Use the migration status tabs to select and view migration activity and statistics.
See Migration status panes (see page 2067) and Migration status tabs (see page 2068).

To control migrations from the migration status pane, click a status tab and then right-click a status
line to open a menu with the following options:
Start — Starts a scheduled migration (before its scheduled time).

Restart — Restarts an interrupted or stopped migration (starting from the point of
interruption and going forward).
Stop — Stops any type of migration.
Delete — Deletes an interrupted, stopped, scheduled, or completed migration, along with
the migration result files.
Migrating objects between servers or files

You can migrate objects between servers, between a server and a file, or between files.
Important
If you have migrated hierarchical groups (groups that include both parent and child
groups), the Differences report might show a difference between source and
destination. This could be because a child group was migrated but not its parent.
To resolve this difference, migrate both parent and child groups.
You cannot compare association object in BMC Remedy Migrator.
You cannot migrate your association object from .migrator or .def file to a server
and from a server to a .migrator or .def file.
1. Open windows for your source and destination.

To open a window for a server, select File > New Server Window, and select a
server.
To open a window for a file, select File > Open, and select a file.
2. Click in the source window.
3. Select Migrate > Migration Mode.
4. From the Migrate menu, select the type of object migration to perform:
All BMC Remedy AR System Objects — Migrate all objects listed in the source
window.
Form and Related Objects — Migrate a form and all of its related objects.
Deploy Application — Migrate an application and all of its objects to the same server.
See Migrating applications (see page )
Selected Objects — Migrate only the objects selected in the source window.
5. From the Destination Type dialog box, select the destination type by clicking Server or
Migrator File.

5.
If you select Server, select a destination server and enter your user name and
password.
The source server is always the server window that is active at the time of the
migration. To review object differences on the same server, select the same
destination server as your source, and then add a prefix when prompted by the Prefix
dialog box.
If you select Migrator File, enter the file destination path, type a file name, and click
Save. The migration is saved as a .migrator file.
6. If you are prompted to proceed with the migration, select Yes.
7. To view the progress and results of your migration, open the Migration Status pane by
choosing View > Migration Status if it is not already open.
Select the All tab to see the progress of the migration; select the Completed tab to
see a list of completed migrations.
To view a results report for a completed migration, double-click the migration in the
Completed tab. For more information about results reports, see Migration Result
reports (see page ).
Migrating applications
You can migrate an application to another server, to the same server, between a server and a file,
or between files using two methods:
By migrating it as a selected object (Migrate > Selected Object).

By deploying it (Migrate > Deploy Application). This method migrates the application and all
of its supporting files.
Migrating applications

Migrating an application as a selected object (see page 2124)

Deploying an application (see page 2124)
Migrating an application as a selected object
1. Open the server or file window that includes the application you want to migrate.
2. In the right pane, select the application.
3. Select Migrate > Selected Objects.
4. From the cascading menu, select Select Destination.
Note
You can also select any server or file listed in the cascading menu.
5. In the Destination Type dialog box, select Server or Migrator File.

If you select Server, select a destination server and, if necessary, enter your BMC
Remedy AR System user name and password.
If you select Migrator file, enter the name of the .migrator file to serve as the
destination.
If you are prompted to proceed with the migration, select Yes.
6. To view the progress and results of the migration, open the Migration Status pane by
choosing View > Migration Status.
Deploying an application
When you deploy an application, BMC Remedy Migrator migrates the application and all of its
supporting objects to the destination.

Migrating application data to a file without a corresponding form
When creating an application using BMC Remedy Developer Studio, you can specify the data to
be exported when the application is deployed. This information is shown in the Data tab in the
Modify Application dialog box.
In BMC Remedy Migrator, when you deploy an application that contains data for forms that the
application does not own, those forms are not automatically migrated. However, BMC Remedy
Migrator provides an option to migrate forms required by applications at deployment. When this
option is set to Yes, the forms required by the application are included with the data in the
migration.
Required Objects option: Migrate Fields Required by Applications
If this option is set to No when you deploy an application that contains data for forms that the
application does not own, BMC Remedy Migrator creates a special data-only form to receive the
data being migrated. In the Object List window, this form is listed as a data-only form with a
different icon than that of a regular form or a display-only form.
Data-only form

During the migration, the data in this form is migrated, but not the form itself.
For more information about required objects options in BMC Remedy Migrator, see Selecting
objects to migrate (see page ).
Deploying an application to the same server
If you have an BMC Remedy AR System 6.0 or later server, you can deploy an application to the
same server as a copy/prefix migration. See Migrating objects to the same server (see page 2135).
To deploy an application
1. Open the server or file window that includes the application to deploy.
2. In the right pane of the window, select the application.
3. Select Migrate > Deploy Application.
4. From the cascading menu, select Select Destination.
Note
You can also select any server or file listed in the cascading menu.
5. In the Destination Type dialog box, select Server or Migrator File.

If you select Server, select a destination server and, if necessary, enter your BMC Remedy
AR System user name and password.
If you select Migrator file, enter the name of the .migrator file to serve as the destination.
If you are prompted to proceed with the migration, select Yes.
6. To view the progress and results of your migration, open the Migration Status pane by
choosing View > Migration Status if it is not already open.
Migrating a form view and its associated fields

You can select a view of a form and its fields, and the display properties associated with that view
instead of having to select all the fields and views for the form.

When a field is added to view overlay by using the Add Field To View Overlay menu item, a field
ID is assigned to it. When a view is selected for migration, BMC Remedy Migrator searches for all
of the fields with display properties for that view. BMC Remedy Migrator then migrates that view
and its associated fields to the destination form. It checks each field on the destination form and
takes the appropriate action:
If the field exists on the destination, BMC Remedy Migrator extracts the display properties
from the destination field for all views except the view being migrated.
It merges these display properties into the source field and compares the properties of the
source field with those of the destination field.
If the field does not exist on the destination, BMC Remedy Migrator recreates the field, and
verifies that the field includes only the display properties of the field being migrated.
Finally, BMC Remedy Migrator creates or modifies the field on the destination by using the
new merged source field.
If the field exists on the destination, BMC Remedy Migrator extracts from the destination
field the display properties for all views except the view being migrated.
This process is repeated for each field in the view. BMC Remedy Migrator migrates any new
values for the object properties in a view overlay form. All types of migration is supported for a view
overlay form.
Note
BMC Remedy Migrator does not remove field and view overlays from the destination
server after migration, even if you remove the field and view overlays from the source
server.
To migrate a form view and its fields
1. In the BMC Remedy Migrator main window, select the form whose view you want to
migrate.
2. Right-click on the form name and select Form Details.
3. From the left panel, select Views.
4. Select the view you want to migrate.
5. Select Migrate > Selected View with Fields > Select Destination.
6. Select a form and click OK.
7. Click Yes in to confirm the migration.
Related topics
Adding a field to a view overlay (see page 3053)

Migrating fields
You can use BMC Remedy Migrator to migrate fields from one BMC Remedy BMC Remedy AR
System form to another. By migrating lower-level fields or field-level objects from one form to
another, you can update forms at a more basic level. For example, you can migrate a Middle Name
field to a form with only first and last name fields.
To migrate fields
1. Open windows for the source and destination.

server.
3. In the left pane of the source window under BMC Remedy AR System Objects, click Forms.
4. In the right pane of the source window, select the form that includes the fields you want to
migrate.
5. Click View > Form Details, or double-click the form name to open a Form Detail window for
the form.
The right pane lists the fields for the selected form.
Migrating fields
6. Perform one of the following actions:

To migrate all fields, select Migrate > All Fields, or Migrate > All Views.
To migrate fields of a specific type, select Migrate > Migrate Field by Type.
To migrate one or more fields, select the fields in the right pane. Use Shift-Click or
Ctrl-Click to select multiple fields. Then, right-click and select Migrate Selected Fields
from the pop-up menu.
7. From the Destination Type dialog box, select Server or Migrator File.

If you select Server, select a destination server and enter your BMC Remedy AR
System user name and password. You are prompted to select a destination form.
The source server is always the server window you have activated at the time of the
migration. To review object differences on the same server, select the same
destination server as your source, and then define a prefix. For the prefix, use a short
string, such as prod.
If you select Migrator File, select the .migrator file to which the field should be
migrated. A list of forms in the .migrator file is displayed. If the file has no forms in it,
you cannot migrate the field to that file.
9. To view migration progress and results, open the Migration Status pane by choosing View >
Migration Status.
Select the All tab to see the progress of the migration.
Select the Completed tab to see a list of completed migrations.
To view a results report for a completed migration, double-click the migration in the
Completed tab. See Migration Result reports (see page )
Migrating data
You can migrate data entries associated with a form from one server to another, between a server
and a file, or between files. For example, you can migrate data entries from a production server to
a development server for testing newly designed applications with actual data. Or, you can migrate
data from one file to another. Data is migrated individually or in a batch.
Note
If you stop and then restart a migration in progress, BMC Remedy Migrator restarts the
migration from the entry that was last migrated successfully.
By default, BMC Remedy Migrator uses the field IDs to map field values between the two forms
you select. You can migrate four types of data:
Individual entries
All entries
Searched entries
"X" number of entries
Note
Data Migration options are not available for Display Only forms.

Migrating ITSM, SLA, and CMDB data

BMC Remedy Migrator does not take the place of the current ITSM/SLA/CMDB installation
processes, because it cannot execute the meta workflow used to generate workflow required by
the client. BMC Remedy Migrator allows you to safely move generated workflow from the system
on which it was created to a production system without taking the meta workflow with it.
Note
All users must have administrator privileges to use BMC Remedy Migrator. When
migrating ITSM/SLA/CMDB application-related data, you must first verify that they are a
member of the required group or groups, in order for the data to be migrated correctly.
Migrating individual entries in a form (see page 2130)

Migrating data entries (see page 2131)
Migrating individual entries in a form

Perform the following steps to migrate individual data entries in a form.
To migrate individual entries in a form
1. Open a server window or a file containing the data entries you want to migrate.
server.
2. Select Migrate > Migration Mode or Scripting Mode.
3. In both the source and destination windows, perform the following tasks:
a. In the right pane, select the form that is the source or destination for the data
migration.
b. Select View > Form Details to open the Forms Detail window:
4. Scroll to the bottom of the left pane of the source Form Detail window and click Data.
The right pane displays the data for the fields in the form.
Note
The columns displayed in the right pane for the form data are defined by the
settings in the Form Properties dialog box in BMC Remedy Developer Studio. The
Results List Fields tab specifies the fields to be displayed in results lists. If no fields

are specified, BMC Remedy Migrator uses the defaults for the form (field IDs 1 and
8). For example, in the Group form, Request ID and Long Group Name (fields 1
and 8) are displayed. To display additional fields, use BMC Remedy Developer
Studio to enter those fields. See Setting form properties (see page 2394).
The advanced search bar appears at the bottom of the Form Detail window, allowing you to
search for data to include in the migration.
5. Do either of the following actions in the advanced search bar:
To find specific data, enter criteria in the Search Criteria field, and click Apply. The
matching entries are listed in the Form Detail window.
To include all data, leave the Search Criteria field blank.
6. Select the data to migrate:
To migrate only the data found in your search, select the records from the source
Form Detail window and drag and drop them into the destination Form Detail window.
To migrate all the data from a specific form, first select the data in the right pane of
the source Form Detail window. To select all the data records, highlight the first data
record, hold down the Shift key, and then highlight the last data record.
7. Right-click in the right pane of the Form Detail window and select Migrate Selected Entries.
If you are migrating to a server, select the destination server in the Server dialog box.
If you are migrating to a file, enter or select a .migrator file name.
8. Select the destination form in the Form List dialog box.
Migrating data entries

Perform the following steps to migrate forms, data and related objects.
To migrate data entries
1. Open the windows that you want as the source and destination for the data you are
migrating.
server.
2. Select Migrate > Migration Mode or Scripting Mode.
3. Select Migrate > Form Data, then select one of the following options:
Form Data Only--Only the entries within the form are migrated.
Form and Data--Both the form and the entries within the form are migrated.
Form, Related Objects, and Data--Both the form and the entries within the form are
migrated, along with all related objects.
If you are migrating forms and data to the same server, the Prefix dialog box
appears. Enter a prefix.
The
Data Migration Settings dialog box appears.
Data Migration Settings dialog box

The migration is listed at the top of the dialog box with the following information:
Source Name--The name of the server or file from which the data is being migrated.
If the source is a file, the complete file path is shown. A green check mark or a red X
through the icon indicates whether the migration instructions are valid.
Source Form--The name of the form that includes the data being migrated.
Destination Name--The name of the server or . migrator file to which the data is
being migrated. If the destination is a file, the complete file path is shown.
Destination Form--The name of the BMC Remedy AR System form on the destination
to which the data applies.
Object Settings--The objects to be included in the migration, based on what you
selected in step 3 (see page 2131).
Data Mode--The specific data to be migrated. The setting shown is based on the
default value set in your migration options.
Ignore pattern checking (yes/no)--Whether pattern checking should be ignored.
Ignore required fields (yes/no)--whether required fields should be ignored.
Num Entries--The number of entries being migrated.
Search criteria--Any search criteria specified for this migration. If you did not specify
any search criteria, this column is blank.
The Source and Destination areas show the names of the source and destination
servers or files, and forms. For example, if you are migrating between two files, the
source and destination file paths are shown.

Source and Destination information for data migration
4. Select the migration to highlight it.
Selected migration in Data Migration Settings dialog box
Note
If your migration has any invalid instructions, the icon at the left of the server name
has a red cross (X) through it, and a message appears in the lower-left area of the
Data Migration Settings dialog box. You must make sure that all migration
instructions are valid before you can continue.
5. In the Object Settings region, select a setting for the objects to be migrated:
Form Only--Migrates only forms.
Form and Related--Migrates forms and related objects.
Form Data Only--Migrates only form data entries.
Form and Data--Migrates forms and data entries.
Form, Related and Data--Migrates forms, related objects, and data entries.
6. In the Data Settings region, select a data mode. The default selection shown corresponds
with the Data settings in your migration options. For more information about setting
migration options, see Setting BMC Remedy Migrator options (see page 2096). Accept the
selection shown, or select another selection:
No Data --No data entries are migrated. You can set the default setting for this mode
by choosing Tools > Options, expanding the Migration tree in the left pane, and then
selecting Data from the same tree.
All Entries--All entries are migrated according to your selections and settings.
Search Selection--Entries are migrated based on search criteria you specify. If the
source is a file, this selection is not available. For information about creating a
search, see Migrating objects to the same server (see page 2135).

Number of Entries--Number of entries that are migrated, starting from the newest to
the oldest.
7. Select a data merging option. The default selection shown is based on the Data settings in
your migration options. For more information about setting migration options, see Setting
BMC Remedy Migrator options (see page 2096). Either accept the selection shown, or select
another selection:
Reject Duplicate Entries--BMC Remedy Migrator generates an error for entries with
existing request IDs.
Generate New ID for All Entries--BMC Remedy Migrator creates a new request ID for
all entries. If the destination is a file, this selection is not available.
Replace Old Entry with New Entry--BMC Remedy Migrator replaces old entry
information with new entry information.
Update Old Entry with New Entry's Data--BMC Remedy Migrator merges old entry
information with new entry information.
8. For each data merging option selected, check the appropriate check boxes to enable the
following options:
Ignore required fields
Ignore pattern checking
9. Select a default migration mode:
Do not migrate any records
Migrate all records
Migrate query selection
Migrate the first numberOfRecords records
10. Select server connection options:
Use List and Fast Server Threads – By default, BMC Remedy Migrator uses Fast and
List server threads as an alternative to the standard Admin thread. The default setting
for the Fast Thread Port is 390620; the default setting for the List Thread Port is
390635. To change these settings, enter different values. To disable Fast and List
Treads and use the Admin thread, uncheck the box.
11. Check the Disable Related Workflow check box to have BMC Remedy Migrator disable
related workflow during the data migration. The workflow is enabled after the migration is
complete.
12. Check the Enable Field Mappings box to apply field mappings for the data migration. See
Migrating applications and data between AR System servers (see page ).
13. Perform one of the following actions:
Select Apply, then OK, to begin the data migration.
Note
The OK button is disabled until all the migration instructions are valid in the
Data Migrations Settings dialog box.

Click Cancel to stop the data migration.

14. If you are asked if you want to start the migration, select Yes.
15. To view migration progress and results, open the Migration Status Pane window and click
the All and Completed tabs. Then, double-click the migration you want to check.
Migrating objects to the same server

When migrating objects to the same server, you must change the object's prefix so that the objects
have unique names. This is called a Copy-Prefix migration.
Note
When migrating an application to the same BMC Remedy AR System 6.0 or later server,
you might notice that BMC Remedy Migrator does not automatically deploy a prefixed
version of the application. This is because the prefix is applied only to the application
name, not its objects. As a result, you might see an error message stating that the server
cannot create the application because its objects are already owned by the non-prefixed
application. To migrate the application to the same server, select Migrate > Deploy
Application, and select the same server as the destination. This ensures that the prefixed
version of the application is created and that it has referenced objects that are also
migrated.
Also, when a role is migrated to the same server without an application, a prefixed
application name is assigned to the role, but the role name is not prefixed.
To perform Copy/Prefix object migrations
1. Open the window containing the objects you want to copy or migrate.
2. Select the objects you want to migrate.
3. In the Destination Type dialog box, select Server, then select the same server.
Tip
Dragging and then releasing an object within the same server window, or
performing a copy and paste action, also opens the Prefix dialog box.
4.
4. In the Prefix dialog box, perform one of the following tasks:

Prefix dialog box
\
Click Add Prefix, then type the new prefix.
Click Replace First [HTMLUATarsadministeringmigrating:n ] Characters with New
Prefix, type a number, and then type a new prefix.
Click Remove Old Prefix, then type the old prefix.
Click Replace Old Prefix with New Prefix, type in the old prefix, and then type the
new prefix. For the prefix, use a short string (5 or fewer characters).
5. Click OK.
To view the progress and results of your migration, select View > Migration Status.
Note
When viewing the status of a Copy/Prefix migration, the prefix does not appear
with the server name.
Migrating differing objects

When migrating objects in a Differences report, only those objects that differ between the source
and the destination, or that are missing on the destination, are migrated.
To migrate differing objects

2. From the Migrate menu, click the type of Differences migration you want to perform.
For example, you can migrate All Different BMC Remedy AR System Objects or Selected
Object.
3. When the migration is finished, press F5 to refresh the report display.

Migrating dependent objects from a Dependency report

You can migrate dependent objects from a dependency report.
To migrate dependent objects

2. From the Migrate menu, select the type of dependency migration you want to perform.
For example, you can migrate All BMC Remedy AR System Objects and Dependencies or
All Forms and Dependencies.
3. In the Destination Type dialog box, select the destination type by clicking Server or Migrator
File.
a. If you click Server, select the destination server, and click OK. The source server is
always the server window you have activated at the time of the migration. The
objects you select are migrated to the destination server you selected.
b. If you click Migrator File, select the destination path, enter a file name, and click
Save.
Migrating overlay objects and custom objects

This section discusses about the overlay support in BMC Remedy Migrator and explains the
migration process for overlay and custom objects:
Support for overlays and custom objects (see page 2137)

Migration process overview for overlays and custom objects (see page 2141)
Existing overlay migration (see page 2143)
New overlay migration (see page 2144)
Migrating overlays when corresponding overlaid objects do not exist at destination (see
page 2144)
Migrating origin objects for which overlays exist at the destination (see page 2145)
Viewing the customization type in BMC Remedy Migrator (see page 2145)
Support for overlays and custom objects

BMC Remedy Migrator supports preserving customizations with overlays and custom objects by
enabling you to:
Select only overlays or only origin objects in the object list by using a context menu or by
sorting on the Customization Type column
Compare overlays at the source to origin objects at the destination
Compare origin objects at the source to overlays at the destination
Generate a detailed difference report for selected objects only
Generate a detailed difference report for objects that are listed in a BMC Remedy Migrator
instruction file

Generate a BMC Remedy Migrator instruction file for selected objects only
Generate a BMC Remedy Migrator configuration file
Generate a Detailed difference report for differences not permitted in overlays. See Creating
a Migration Instruction file (see page 2138).
In this topic:
Creating a Migration Instruction file (see page 2138)

Comparing objects at the same location (see page 2139)
Creating a Migration Instruction file

Perform the following steps to create a Migration Instruction file to use for comparison.
To create a Migrator Instruction file
1. Select one or more items in the objects list and right-click to bring up the menu.
2. From the right-click menu, select Create Instruction File.
3. Select the source-destination mapping method to handle mapping in the report.
Map Origin to Overlay
Map Overlay to Origin
4. Use the Save As dialog to specify a file and location, and save the instruction file.
BMC Remedy Migrator caches overlays and custom objects along with all origin BMC
Remedy AR System objects and displays them in the objects list. For example, if an overlay
(ALI1_o) exists for an active link (AL1), BMC Remedy Migrator caches both these active
links because they are valid AR System server objects. It displays both AL1 and AL1 _o in
the objects list of the server.
BMC Remedy Migrator also enables you to perform the following operations:
Compare and migrate overlays and custom objects in the same manner as origin BMC
Remedy AR System objects.
When migrating objects, BMC Remedy Migrator does not migrate the overlayProp and
overlayGroup properties. These properties are managed by the server, and their values
are set only when you create an overlay or a custom object. See Customizing applications
using overlays and custom objects (see page 3031).
Compare objects within the same file or on the same AR System server.
See Comparing objects at the same location (see page 2139)
Specify backup and masking options, and create migration scripts and dependency reports
for overlays and custom objects as you would for origin BMC Remedy AR System objects.
Note

BMC Remedy Migrator provides migration and comparison masks for view and field
properties. However, BMC recommends that you do not disable the migration masks. If
you do so, BMC Remedy Migrator does not migrate overlays and custom objects
corresponding to view and field objects that you modified or added in your source setup.
Migrate overlays and custom objects along with origin BMC Remedy AR System objects.
See Migrating overlay objects and custom objects (see page ).
BMC Remedy Migrator supports these operations only for those objects that the AR System
server supports. See Fixing non-permitted modifications in BMC Remedy ITSM
Comparing objects at the same location

You can compare overlay objects that are of same type, having different names and exist in the
same file or on the same AR System server. For example, you can compare an object with its
overlay if they exist on t

BMC Remedy Action Request System 9.1.00 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 Action Request System 9.1.00 PDF

Uploaded by

Copyright:

Available Formats

BMC Software Confidential. BladeLogic Confidential.

BMC Remedy Action Request

Date: 16-Dec-2015 04:24

BMC Remedy Action Request System 9.1 Page 2 of 4838

Planning a server group installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

BMC Remedy Action Request System 9.1 Page 3 of 4838

Modifying the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

BMC Remedy Action Request System 9.1 Page 4 of 4838

Renaming the AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

BMC Remedy Action Request System 9.1 Page 5 of 4838

Configuring the mid tier through a firewall . . . . . . . . . . . . . . . . . . . . . . . . . 424

BMC Remedy Action Request System 9.1 Page 6 of 4838

Sending traps to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

BMC Remedy Action Request System 9.1 Page 7 of 4838

Managing localized Crystal and Web reports . . . . . . . . . . . . . . . . . . . . . . . 591

BMC Remedy Action Request System 9.1 Page 8 of 4838

Starting BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651

BMC Remedy Action Request System 9.1 Page 9 of 4838

Multiplatform issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716

BMC Remedy Action Request System 9.1 Page 10 of 4838

Configuring authentication processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829

BMC Remedy Action Request System 9.1 Page 11 of 4838

Join forms and BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895

BMC Remedy Action Request System 9.1 Page 12 of 4838

Using BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051

BMC Remedy Action Request System 9.1 Page 13 of 4838

Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273

BMC Remedy Action Request System 9.1 Page 14 of 4838

To disable FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424

BMC Remedy Action Request System 9.1 Page 15 of 4838

Managing request IDs in distributed environments . . . . . . . . . . . . . . . . . 1857

BMC Remedy Action Request System 9.1 Page 16 of 4838

Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240

BMC Remedy Action Request System 9.1 Page 17 of 4838

Creating packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2319

BMC Remedy Action Request System 9.1 Page 18 of 4838

Introducing workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2720

BMC Remedy Action Request System 9.1 Page 19 of 4838

Creating overlays to customize objects . . . . . . . . . . . . . . . . . . . . . . . . . . 3049

BMC Remedy Action Request System 9.1 Page 20 of 4838

Active link debugging example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3267

BMC Remedy Action Request System 9.1 Page 21 of 4838

BMC Remedy AR System REST API overview . . . . . . . . . . . . . . . . . . . . . . 3535

BMC Remedy Action Request System 9.1 Page 22 of 4838

Freeing allocated memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3662

BMC Remedy Action Request System 9.1 Page 23 of 4838

BMC Remedy AR System Java API installed files . . . . . . . . . . . . . . . . . . 4253

BMC Remedy Action Request System 9.1 Page 24 of 4838

Using log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4373

BMC Remedy Action Request System 9.1 Page 25 of 4838

Troubleshooting BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . 4657

BMC Remedy Action Request System 9.1 Page 26 of 4838

Troubleshooting full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4689

BMC Remedy Action Request System 9.1 Page 27 of 4838

Troubleshooting AR 623 error during integration . . . . . . . . . . . . . . . . . . . 4777

BMC Remedy Action Request System 9.1 Page 28 of 4838

Getting started (see page 57)

Planning (see page 183)

FAQs and additional resources (see page 4779)

Enhancements to Centralized configuration

For the details, see 9.1.00 enhancements (see page 46).

BMC Remedy Action Request System 9.1 Page 29 of 4838

Release notes and notices

To stay informed of changes to this space, place a watch on this page.