BMC 7.0 Workflow Objects AR System User manual

BMC® Remedy® Action Request System® 7.0
Workflow Objects
May 2006
Part No: 58468
Copyright 1991–2006 BMC Software, Inc. All rights reserved.
BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and
all other BMC Software product or service names, are registered trademarks or trademarks of BMC
Software, Inc. All other trademarks belong to their respective companies.
BMC Software, Inc., considers information included in this documentation to be proprietary and
confidential. Your use of this information is subject to the terms and conditions of the applicable end user
license agreement or nondisclosure agreement for the product and the proprietary and restricted rights
notices included in this documentation.
For license information about the OpenSource files used in the licensed program, please read
OpenSourceLicenses.pdf. This file is in the \Doc folder of the distribution CD-ROM and in the
documentation download portion of the product download page.
Restricted Rights Legend
U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE
COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the
U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS
252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is
BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.
Contacting Us
If you need technical support for this product, contact Customer Support by email at [email protected].
If you have comments or suggestions about this documentation, contact Information Development by
email at [email protected].
This edition applies to version 7.0 of the licensed program.
BMC Software, Inc.
www.bmc.com
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . 10
Learn about the AR System Developer Community . . . . . . . . . . . . 12
Why should you participate in the Developer Community? . . . . . . . . 12
How do you access the Developer Community? . . . . . . . . . . . . . 12
Chapter 1
Introducing workflow . . . . . . . . . . . . . . . . . . . . . . . 13
Workflow objects . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
Active links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Escalations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
General procedures . . . . . . . . . . . . . . . . . . . . . . . . . 17
Using the workflow windows . . . . . . . . . . . . . . . . . . . . . . 17
Shared workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Sample uses of shared workflow . . . . . . . . . . . . . . . . . . . . 24
Chapter 2
Setting workflow conditions . . . . . . . . . . . . . . . . . . . 25
Defining workflow basics . . . . . . . . . . . . . . . . . . . . . . . . 26
Workflow conditions . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 3
Building qualifications . . . . . . . . . . . . . . . . . . . . . . 33
Qualification basics . . . . . . . . . . . . . . . . . . . . . . . . . .
34
Fields in qualifications . . . . . . . . . . . . . . . . . . . . . . . . . 35
Values in qualifications . . . . . . . . . . . . . . . . . . . . . . . . 37
Contents 3
BMC Remedy Action Request System 7.0
Status history in qualifications . . . . . . . . . . . . . . . . . . . . . 38
Tips for improving system performance when creating qualifications . . . . 39
Checking transaction versus database values . . . . . . . . . . . . . . . 40
Filter qualification examples . . . . . . . . . . . . . . . . . . . . . 41
Chapter 4
Specifying workflow actions . . . . . . . . . . . . . . . . . . . 45
If actions and Else actions . . . . . . . . . . . . . . . . . . . . . . . 46
Creating and modifying actions . . . . . . . . . . . . . . . . . . . . . 48
Types of workflow actions . . . . . . . . . . . . . . . . . . . . . . . 51
The Call Guide active link or filter action . . . . . . . . . . . . . . . . . 53
The Change Field active link action . . . . . . . . . . . . . . . . . . . 54
Defining advanced change field action functions . . . . . . . . . . . . . 58
The Close Window active link action. . . . . . . . . . . . . . . . . . . 61
The Commit Changes active link action . . . . . . . . . . . . . . . . . 62
The DDE active link action . . . . . . . . . . . . . . . . . . . . . . . 63
The Direct SQL active link, filter, or escalation action . . . . . . . . . . . 64
The Exit Guide active link or filter action . . . . . . . . . . . . . . . . . 66
The Go To Guide Label active link or filter action . . . . . . . . . . . . . 66
The Goto active link or filter action . . . . . . . . . . . . . . . . . . . 66
The Log to File filter or escalation action . . . . . . . . . . . . . . . . . 68
The Message active link or filter action . . . . . . . . . . . . . . . . . . 69
The Notify filter or escalation action . . . . . . . . . . . . . . . . . . . 72
The OLE Automation active link action . . . . . . . . . . . . . . . . . 78
The Open Window active link action . . . . . . . . . . . . . . . . . . 78
Using advanced Open Window action functions . . . . . . . . . . . . . 94
The Push Fields active link, filter, or escalation action . . . . . . . . . . . 97
Defining advanced Push Fields action functions . . . . . . . . . . . . 101
The Run Macro active link action . . . . . . . . . . . . . . . . . . . . 106
The Run Process active link, filter, or escalation action . . . . . . . . . . . 108
Command line syntax guidelines . . . . . . . . . . . . . . . . . . 111
The Set Fields active link, filter, or escalation action . . . . . . . . . . . . 112
Defining advanced Set Fields action functions . . . . . . . . . . . . . 120
The Wait active link action . . . . . . . . . . . . . . . . . . . . . . . 124
Specifying escalation time criteria . . . . . . . . . . . . . . . . . . . . 124
4 Contents
Workflow Objects
Chapter 5
Defining guides and guide actions . . . . . . . . . . . . . . . 127
Process for creating guides . . . . . . . . . . . . . . . . . . . . . . . 128
Defining guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Defining guide basics . . . . . . . . . . . . . . . . . . . . . . . 131
Defining the active links or filters in a guide. . . . . . . . . . . . . . 133
Setting permissions . . . . . . . . . . . . . . . . . . . . . . . . 134
Building and using guide change history . . . . . . . . . . . . . . . 135
Creating help text for guides . . . . . . . . . . . . . . . . . . . . 135
Logging guide activity . . . . . . . . . . . . . . . . . . . . . . . . 135
Modifying guides . . . . . . . . . . . . . . . . . . . . . . . . . 135
Deleting guides . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Shared guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Shared guide examples. . . . . . . . . . . . . . . . . . . . . . . 137
Guide actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
The Call Guide active link or filter action . . . . . . . . . . . . . . . 138
The Exit Guide active link or filter action . . . . . . . . . . . . . . . 144
The Go To Guide Label active link or filter action . . . . . . . . . . . 145
The Wait active link action . . . . . . . . . . . . . . . . . . . . . 146
Active link guides . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
How active links interact with guides. . . . . . . . . . . . . . . . . 150
Using active link guides in client-side table fields. . . . . . . . . . . . 153
Using interactive active link guides . . . . . . . . . . . . . . . . . 155
Filter guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Using filter guides in server-side table fields . . . . . . . . . . . . . . 163
Chapter 6
Using buttons and menu bar items to execute active links . . . . 169
Understanding how buttons and menu items work with active links . . . . . 170
Active links as menu items . . . . . . . . . . . . . . . . . . . . . . . 171
Changing the order of menu items and toolbar buttons . . . . . . . . . . 175
Associating active links with buttons and menu items . . . . . . . . . . . 176
Deleting buttons and menu items . . . . . . . . . . . . . . . . . . . . 178
Contents 5
BMC Remedy Action Request System 7.0
Chapter 7
Workflow processing . . . . . . . . . . . . . . . . . . . . . . 181
Active link processing . . . . . . . . . . . . . . . . . . . . . . . . . 182
Filter processing in the AR System server . . . . . . . . . . . . . . . . . 184
Filter execution order . . . . . . . . . . . . . . . . . . . . . . . 184
Filter phases . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Tracing active link, filter, or escalation activity . . . . . . . . . . . . . . 196
Appendix A
Operators, wildcards, keywords, and NULL values . . . . . . . . 197
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Operator types . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Operator precedence . . . . . . . . . . . . . . . . . . . . . . . 201
Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
The NULL value, relational algebra, and AR System . . . . . . . . . . . . 210
The NULL value . . . . . . . . . . . . . . . . . . . . . . . . . 210
Relational algebra and qualifications involving NULL . . . . . . . . . 210
The NULL value and AR System . . . . . . . . . . . . . . . . . . 212
Appendix B
Additional ways to use the Set Fields action . . . . . . . . . . . 213
Assigning values by submitting SQL commands . . . . . . . . . . . . . . 214
Performing the SQL operation . . . . . . . . . . . . . . . . . . . 218
Assigning values by issuing requests to a Filter API Plug-In service . . . . . 219
Assigning values using function results. . . . . . . . . . . . . . . . . . 222
Specifying arguments that use a comma as a decimal separator. . . . . . 223
Assigning values from process results . . . . . . . . . . . . . . . . . . 234
Assigning values by using arithmetic operators . . . . . . . . . . . . . . 237
Appendix C
Special Run Process and $PROCESS$ commands . . . . . . . . . 239
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Run Process and $PROCESS$ syntax . . . . . . . . . . . . . . . . . . 240
Syntax exception—Special commands with qualifications . . . . . . . . . 241
Table of Run Process and $PROCESS$ commands . . . . . . . . . . . . 242
Sending events to the Data Visualization definitions . . . . . . . . . . . . 259
6 Contents
Workflow Objects
Appendix D
Workflow extras. . . . . . . . . . . . . . . . . . . . . . . . . 261
Sending events between windows . . . . . . . . . . . . . . . . . . . . 262
Additional considerations for sending events . . . . . . . . . . . . . 263
Example of sending events between windows . . . . . . . . . . . . . 264
Using workflow to “walk” a table field . . . . . . . . . . . . . . . . . . 268
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Contents 7
BMC Remedy Action Request System 7.0
8 Contents
Preface
Important: The compatibility information listed in the product
documentation is subject to change. See the compatibility matrix at
http://supportweb.remedy.com for the latest, most complete information
about what is officially supported.
Carefully read the system requirements for your particular operating
system, especially the necessary patch requirements.
Audience
This guide is written for developers and administrators who create,
customize, and maintains applications based on BMC® Remedy® Action
Request System®® (AR System®).
Note: You should be familiar with BMC Remedy User and BMC Remedy
Alert before you begin.
This manual contains reference information and procedures for creating,
modifying, and maintaining AR System workflow objects, including active
links, filters, and escalations.
Preface 9
BMC Remedy Action Request System 7.0
AR System documents
The following table lists documentation available for AR System products.
Unless otherwise noted, online documentation in Adobe Acrobat (PDF)
format is available on AR System product installation CDs, on the Customer
Support site (supportweb.remedy.com), or both.
You can access product Help through each product’s Help menu or by
clicking on Help links.
Title
Description
Concepts
Overview of AR System architecture and features with Everyone
in-depth examples; includes information about other
AR System products as well as a comprehensive glossary
for the entire AR System documentation set.
Installing
Procedures for installing AR System.
Getting Started
Introduces topics that are usually only learned when first Everyone
starting to use the system, including logging in, searching
for objects, and so on.
Form and Application Objects
Describes components necessary to build applications in Developers
AR System, including applications, fields, forms, and
views.
Workflow Objects
Contains all of the workflow information.
Developers
Configuring
Contains information about configuring AR System
servers and clients, localizing, importing and exporting
data, and archiving data.
Administrators
Installing and Administering
BMC Remedy Mid Tier
Contains information about the mid tier, including mid Administrators
tier installation and configuration, and web server
configuration.
Integrating with Plug-ins and
Third-Party Products
Discusses integrating AR System with external systems
using plug-ins and other products, including LDAP,
OLE, and ARDBC.
Optimizing and
Troubleshooting
Server administration topics and technical essays related Administrators
to monitoring and maintaining AR System for the
purpose of optimizing performance and troubleshooting
problems.
10 Preface
Audience
Administrators
Administrators
/Developers
Workflow Objects
Title
Description
Audience
Database Reference
Database administration topics and rules related to how Administrators
AR System interacts with specific databases; includes an
overview of the data dictionary tables.
Administering BMC Remedy
DSO
Server administration and procedures for implementing Administrators
a distributed AR System server environment with the
BMC Remedy Distributed Server Option (DSO).
Administering BMC Remedy
Flashboards
Flashboards administration and procedures for creating Administrators
and modifying flashboards and flashboards components /Programmers
to display and monitor AR System information.
C API Reference
Information about AR System data structures, C API
function calls, and OLE support.
Administrators
/Programmers
C API Quick Reference
Quick reference to C API function calls.
Administrators
/Programmers
Java API 1
Information about Java classes, methods, and variables
that integrate with AR System.
Administrators
/Programmers
Administering BMC Remedy
Email Engine
Procedures for installing, configuring, and using the
BMC Remedy Email Engine.
Administrators
Error Messages
List and expanded descriptions of AR System error
messages.
Administrators
/Programmers
Master Index
Combined index of all books.
Everyone
Release Notes
Information about new features list, compatibility lists,
international issues, and open and fixed issues.
Everyone
BMC Remedy User Help
Procedures for using BMC Remedy User.
Everyone
BMC Remedy Import Help
Procedures for using BMC Remedy Import.
Administrators
BMC Remedy Administrator
Help
Procedures for creating and modifying an AR System
application for tracking data and processes.
Administrators
BMC Remedy Alert Help
Procedures for using BMC Remedy Alert.
Everyone
BMC Remedy Mid Tier
Configuration Tool Help
Procedures for configuring the BMC Remedy Mid Tier. Administrators
1.
A JAR file containing the Java API documentation is installed with the AR System server.
Typically, it is stored in C:\Program Files\AR System\Arserver\Api\doc\ardoc70.jar on
Windows and /usr/ar/<server_name>/api/doc/ardoc70.jar on UNIX.
AR System documents 11
BMC Remedy Action Request System 7.0
Learn about the AR System Developer Community
If you are interested in learning more about AR System, looking for an
opportunity to collaborate with fellow AR System developers, and searching
for additional resources that can benefit your AR System solution, then this
online global community sponsored by BMC Remedy is for you.
In the Developer Community, you will find collaboration tools, product
information, resource links, user group information, and be able to provide
BMC Remedy with feedback.
The Developer Community offers the following tools and information:
Community message board
Community Downloads
AR System Tips & Tricks
Community recommended resources
Product information
User Experience Design tips
Why should you participate in the Developer Community?
You can benefit from participating in the Developer Community for the
following reasons:
The community is a direct result of AR System developer feedback.
BMC Remedy provides unsupported applications and utilities by way of
Community Downloads, an AR System application.
BMC Remedy posts the latest AR System product information in the
Developer Community to keep you up to date.
It is an opportunity to directly impact product direction through online
and email surveys.
It’s free!
How do you access the Developer Community?
Go to supportweb.remedy.com, and click the Developer Community link.
12 Preface
Chapter
1
Introducing workflow
This section introduces the three AR System workflow objects: active links,
filters, and escalations. With workflow, you can define a set of processes to
enforce business rules such as tracking company benefits, defects, assets, and
so on.
Note: In this guide, the term button refers to a button that you place in a form
to execute an active link; the term toolbar button refers to a button in a
toolbar, which, in the case of active links, is the toolbar in BMC Remedy
User. A menu bar item refers to the items displayed from a top-level menu
in BMC Remedy User. Do not confuse it with a menu attached to a field.
The following topics are provided:
Workflow objects (page 14)
Using the workflow windows (page 17)
Shared workflow (page 22)
Introducing workflow 13
BMC Remedy Action Request System 7.0
Workflow objects
Workflow objects automate your organization’s business processes. You can
create active links, filters, and escalations to perform actions on one form or
several. When workflow is attached to multiple forms, it is considered shared
workflow. See “Shared workflow” on page 22 for more information.
Active links, filters, and escalations share many similarities, but also have
several differences that are described in this section. See the Concepts guide
for background information about workflow.
Active links
An active link is an action or a series of actions that are conditionally
interpreted after being triggered when a user performs an operation, based
on the set of permissions assigned to that user. The interpretation occurs on
the AR System client in the current form window. For example, you might
define an active link that displays a list of all problems reported for the
current workstation whenever a user presses ENTER in the Workstation
field.
When an active link is executed from a form, you can trigger multiple active
links with a single user action. Because you can also specify the conditions
under which an active link executes, you can define an active link where a
single user action leads to different active link results. For example, you can
design an active link that checks the group membership of the name in the
Submitter field and, based on the group membership, attaches a different
menu to the Short Description field. This would enable you to provide one
set of descriptive options to someone in Human Resources and a different set
of options to someone in Shipping.
Active links can be grouped into execution groupings called active link guides
that allow procedural processing (discussed in the Form and Application
Objects guide).
Note: Active links cannot be triggered through the use of an API program.
14 Chapter 1—Introducing workflow
Workflow Objects
Filters
You can design filters to implement and enforce your organization’s business
rules because filters test every request transaction to see if certain conditions
are met, and then respond to the conditions by taking specific actions. For
example, you might define a filter that notifies support staff members when
they are assigned responsibility for a new request.
Filters can act on virtually any condition that arises in a request. For example,
filters can restrict how users create or modify a request. Filters can also check
for conditions in requests that are submitted by a network management
system for a device that the system is monitoring. Then the filter can
automatically call a program to control that device.
Filters execute on the AR System server and run with administrator
permissions. This means that filters can access any field in the AR System
database, even if the field is not available to the user (no view or change
access).
Filters can be grouped into filter guides. For more information, see Chapter
5, “Defining guides and guide actions.”
Escalations
An escalation enables a condition to be checked on a regular basis and,
depending on if and how it is met, performs one or more actions. For
example, you might define an escalation that sets the priority to Urgent if the
request is not closed within 24 hours. Or you might choose to page a support
staff member if a Critical request has not been addressed in one hour.
Escalations execute on the AR System server and run with administrator
permissions. Escalations differ from filters in that escalations occur at a
specific point on a time interval rather than in response to a specific
operation. Additionally, escalations are scheduled to act on requests that
meet a certain qualification, while filters act on the current request
(transaction).
At the times specified within the escalation, AR System searches for requests
that match the escalation qualification, and performs the specified escalation
actions on requests that match.
Workflow objects 15
BMC Remedy Action Request System 7.0
The following table compares the functionality of active links, filters, and
escalations.
Active Links
Where performed Client, current form
window
Filters
Escalations
Server
Server
Executed by
A user performing an action A specific operation
A specific time
Purpose
Help the user to do
something
Get someone to do
something
What they do
Start a series of actions that Test every AR System server
are conditionally
transaction to see if certain
interpreted
conditions are met and
respond by taking specific
actions
Enable a condition to be
regularly checked, and
depending on if and
how it is met, perform
actions
Runs as
User
Administrator
Administrator
Example
Display all problems
reported for the current
machine whenever a user
presses Enter in the
Machine Name field
Notify support staff
members when they are
assigned a new request
Page a support staff
member if a Critical
request has not been
addressed in one hour
16 Chapter 1—Introducing workflow
Implement and enforce the
rules
Workflow Objects
General procedures
Although active links, filters, and escalations have different purposes and
properties, they share many similarities that are shown in the following table.
For Information about
See
Creating, copying, renaming, and deleting
AR System objects
The Getting Started guide.
Assigning permissions (enables you to specify users The Configuring guide.
and groups who can access an object)
Entering change history (a record of an object’s
owner, the user who last modified the object, and
the date of modification)
The Getting Started guide.
Creating and modifying help text for objects
The Getting Started guide.
Creating a log file for tracing object activity (You
can create a record of an object’s operation,
including what executed and whether it was
successful.)
“Tracing active link, filter, or
escalation activity” on
page 196.
Using the workflow windows
You can open multiple windows for creating or modifying the active links,
filters, and escalations that you have permission to administer. The title bar
of each window tells you whether you are working in the Active Link, Filter,
or Escalation window. Use the Active Link window, shown in the following
figure, to create and modify active links.
Using the workflow windows 17
BMC Remedy Action Request System 7.0
Figure 1-1: Active Link window
Use the Filter window, shown in the following figure, to create and modify
filters.
18 Chapter 1—Introducing workflow
Workflow Objects
Figure 1-2: Filter window
Use the Escalation window, shown in the following figure, to create and
modify escalations.
Using the workflow windows 19
BMC Remedy Action Request System 7.0
Figure 1-3: Escalation window
20 Chapter 1—Introducing workflow
Workflow Objects
Use the following tabs in each of the workflow windows to define active links,
filters, or escalations:
Basic
Defines the basic properties; what the user must do to
execute it (for active links only) or the conditions that cause
it to execute; enabling or disabling the workflow object; and
a qualification. For example:
An active link executes when the user presses Return in a
specified field or clicks a button on the form.
A filter executes when a user submits a request.
An escalation executes when a request more than eight
hours old has not been closed by support personnel.
If Action
Defines the actions that will execute when the qualification
is met. For example:
An active link qualification looks for a specific name in the
Submitter field, and the If action allows access to a field.
A filter qualification looks for “hardware” in the Problem
Type field, and the If action automatically delegates the
request to a hardware support person.
An escalation qualification looks for “New” in the Status
field for any request more than two hours old, and the If
action assigns the request to the manager.
Else Action
Defines the actions that will execute when the qualification
is not met. For example:
An active link qualification looks for a specific name in the
Submitter field, and the Else action denies access to a field.
A filter qualification looks for “hardware” in the Problem
Type field, and the Else action automatically delegates the
request to a software support person.
An escalation qualification looks for “Active” in the Status
field for any request more than two hours old, and the Else
action sends an email notification to a shared status log
account.
The Else action is optional.
Permissions (active Defines those access control groups that are allowed to
links only)
execute the active link.
Time Criteria
Defines when the AR System server will check the escalation
(escalations only)
conditions.
Using the workflow windows 21
BMC Remedy Action Request System 7.0
Change History
Records the owner, the user who last modified it, and the
date of the modification. You can also enter a description of
your changes.
Help Text
Supplies help text. In most cases, this help text is a
description of what the workflow object does, and how it is
used.
Shared workflow
You can create workflow (active links, filters, and escalations) that can be
attached to one or multiple forms. For example, you could create an
employee information active link that would populate generic identification
and address fields anytime a user enters a name, and use this on multiple
forms.
Shared workflow lets you efficiently build, maintain, and troubleshoot
versions of forms and applications. Fewer workflow objects need to be stored
on the server because any changes you make only need to be made once for
all forms that use the objects.
WARNING: Sharing active links and active link guides among forms in
different deployable applications requires caution. Role permissions are
resolved based on which application has ownership. The owner
application contains the form that is the primary or reference form in the
active link or active link guide. The non-owner application might have
identical roles mapped to different groups, but these mappings are
ignored. If only implicit groups have permission (no role permissions),
there are no conflicts. For more information, see the Form and Application
Objects guide.
The way you define shared active links, filters, or escalations is similar to the
way you define workflow for an individual form. The main difference is that
instead of attaching the workflow to one form, you attach it to multiple
forms. If you do not want the workflow to be shared, select only one form.
See “Defining workflow basics” on page 26 for instructions on creating
workflow.
Workflow actions interact with fields based on field ID (not the field name)
on each of the forms to which the field ID is attached.
22 Chapter 1—Introducing workflow
Workflow Objects
Because shared workflow uses any valid field ID, plan how you want to use
shared workflow before attaching it to multiple forms. Multiple forms that
share workflow can show different field names for fields with the same ID. To
make it easier to administer shared workflow, create fields with the same ID
and the same field name on each form to help you remember the purpose of
the field. Otherwise, the workflow might not fire, or the shared workflow
actions will still be triggered but might not use the expected field. In either
case, the action you expect to happen—because you have connected the
workflow to a non-existing field or the wrong field—will have no effect
(depending upon the workflow).
Finally, if fields have matching IDs but are different data types, AR System
will convert them appropriately.
After you have created a form with which you want to share workflow, you
can:
Create a new workflow object and then attach it to forms.
Select an existing workflow object and then attach it to forms.
WARNING: When you create a copy of a field to put on another form, the new
field retains all of the properties of the original field including the field ID.
Use caution when using different field names that share the same field ID
since shared workflow uses the field ID to trigger actions.
When exporting definitions, you can choose whether to maintain an
association between the selected workflow and all related forms. See the Form
and Application Objects guide for more information.
When you delete a form that uses non-shared workflow, the workflow is
deleted along with the form. However, if workflow is shared by multiple
forms, it will not be deleted until the last form that uses it is deleted.
Shared workflow 23
BMC Remedy Action Request System 7.0
Sample uses of shared workflow
Possible ways to use shared workflow include:
Populating common fields used to store employee data.
Automatically assigning cases (based on tasks and applications).
Accessing common forms such as bulletin boards, reporting, preferences,
reminders, and so on.
Navigating, for example, in a configuration tool.
Displaying a message or warning dialog box that appears whenever a user
submits a form or enters invalid information.
24 Chapter 1—Introducing workflow
Chapter
2
Setting workflow conditions
This chapter describes how to set specifications and conditions in the Basic
tab of the Active Link window, the Filter window, and the Escalation
window. The following topics are provided:
Defining workflow basics (page 26)
Workflow conditions (page 28)
Setting workflow conditions 25
BMC Remedy Action Request System 7.0
Defining workflow basics
Use the following procedure to define workflow basics.
From the Basic tab, you can define the criteria that an operation must meet
before the corresponding actions take place. The basics include:
Basics
The name
Whether it is enabled
The order in which it will execute in
relation to others
The form or forms to which it applies
How users will invoke it
Active Links Filters
The operations that will invoke it
The qualification that determines
whether If actions or Else actions are
executed
Escalations
To define workflow basics
1 Create or open a workflow object with which you want to work.
See the Getting Started guide for more information.
2 In the Name field, enter a name (or update the existing name if necessary).
Names must be unique on each AR System server. Names can be as many as
80 characters, including spaces. Names can include double-byte characters,
but avoid using numbers at the beginning of the name.
Be aware that clients prior to the 5.x version will have trouble recognizing
and properly executing client-side workflow when the name is longer than 30
characters.
26 Chapter 2—Setting workflow conditions
Workflow Objects
3 Select or clear the Enable check box to enable or disable the workflow object.
You might want to disable it during development or when you are
diagnosing a problem.
4 In the Execution Order field for active links and filters, enter the execution
order.
The value that you enter in the Execution Order field determines the order it
will execute relative to others with the same triggering condition. Numbers
between 0 and 1000 are valid execution order values; the lower numbers are
processed first.
You can assign the same number more than once; however, you cannot
control the processing order when there is the same execution order. (The
default value is 0 for active links and 500 for filters.)
Although filters are processed in execution order, some filter actions are
queued up to be performed at a later time. For a detailed explanation on filter
phases, see “Filter processing in the AR System server” on page 184.
5 From the Form Name list, select the forms to which the workflow object
applies.
The workflow will be attached to all of the forms you select. The first form
you select becomes the reference form and appears checked at the top of the
list in bold text. (To change to a different reference form, right-click on any
of the selected forms and use the context menu.) The field names that are on
the reference form appear in the Basic (and Action) tabs. Shared workflow,
however, can use fields that are not on the reference form, if you enter their
field IDs. If you use other forms’ field names that differ from those on the
reference form, these names will not be listed or used in the Basic and Action
tabs used to define this workflow object.
Note: Use caution when sharing active links among forms in different
deployable applications. Role mappings for active links are determined by
the deployable application that owns the active link. The deployable
application that contains the active link's primary form owns that active
link. For more information, see “Shared workflow” on page 22.
When selecting forms from the list, you can:
Use the keyboard arrow key or type a letter to scroll through the list.
Use the spacebar to select or clear a form.
Defining workflow basics 27
BMC Remedy Action Request System 7.0
6 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the workflow object only to the forms in the
application.
Clearing the Restricted List check box lets you access all the forms on the
server.
7 For active links and filters, in the Execute On region, select the operations
that will activate it.
Available operations for active links and filters are listed in the following
section. You can select any combination of these execution conditions. If you
select multiple options, the active link or filter will execute when any one of
the selected operations occurs.
For active links, you can assign an execution condition later if you do not
select one now. If an active link is part of a guide, you need not select an
execution condition. If an action generates an error during the processing of
an active link, no further actions occur.
Workflow conditions
You can select any of the following conditions to activate an active link or
filter.
Condition
Description
Submit
Executes when a user submits a new request. The active link will be executed before
the request is sent to the server.
After Submit
Executes after a user submits a new request and after the request is written to the
database. If the submission fails, the active link will not be executed.
If you use this condition for a set fields action on the current entry, the set value will
not be stored in the database.
Display
Executes after an existing request is loaded into a form, but before the request
appears in the Details Pane.
Un-Display
Executes when a request is removed from the Details pane because a new request
was selected in the Results pane or because the window is closing. The workflow
actions execute before the request is removed from the form.
Modify
Executes when a user modifies an existing request. (The active link will not execute
during a Modify All operation.) The active link will be executed before the request
is sent to the server.
28 Chapter 2—Setting workflow conditions
Workflow Objects
Condition
Description
After
Modify
Executes when a user modifies an existing request and after the request is written to
the database. (The active link will not execute during a Modify All operation.) If the
modification fails, the active link will not be executed.
Set Default
Executes when the user chooses Edit > Set to Defaults from the menu bar. It can
happen after Window Open, and default field values have been set in the form
through user preferences.
Copy To New
Executes when a user chooses Edit > Copy to New in BMC Remedy User. The active
links will be executed after the data has been sent to the new window, so that the
administrator has the ability to use this data in the workflow. Application
developers will find this Copy To New condition particularly useful for:
Validating data when it is copied to a new submit form.
Disallowing the Copy To New function based on workflow. If an error is
returned, no copy is performed and the form remains on the original window.
Search
Executes when a user performs a search operation. If you select this option, the
active link executes before the search operation so that, if the active link criteria is
not met, the If actions will not be performed. (If Else actions exist, they will be
performed.)
To prevent a search from occurring, you can have the active link return a message
(such as an error); otherwise, the search will be performed. You can also use active
links to set fields to modify the search.
Note: The active link can access and assign values in the Search window, including
the Search Bar if the reserved Search Bar field is present on the form.
Window Open
Executes when any of the following actions occur:
A form window opens in New, Search, Modify, or Modify All operation mode.
The mode of the Detail pane switches into one of the above modes.
The form is opened by using the Open Window action.
This is useful for establishing initial environments when users open a new window
or change modes. The active link will be executed before any data is loaded into the
window, except when the form is opened in Dialog mode by the Open Window
action.
Note: When you open a form and the preference is set to Clear All Fields On Search
or On New, any active links with an execution condition of Window Open are
executed. Then, all of the fields in the form are cleared, and finally the active links
with the Window Loaded condition are executed. To make sure a table field is
refreshed after the form is opened, use the Window Loaded execution condition.
Window Close
Executes when a user closes a window.
Workflow conditions 29
BMC Remedy Action Request System 7.0
Condition
Description
Window Loaded
Executes after all the data values have been loaded into a Submit or Search window
(from defaults, from a copy to new, or from an open window action).
Event
Executes when a window has changed its application state, for example, when one
window wants to send an event to one or more windows; when one window has
caused data to change and another window references that data; or when one
window is closed and other windows need to be notified. This capability allows one
part of an application in a client environment to notify other parts that an “event”
has occurred. Other parts of the application can then react by performing actions
such as refreshing table fields.
The Event condition provides a mechanism for a parent window to be notified
when a child window has been closed in the context of a single client environment
(for example, in a browser or in BMC Remedy User), so that workflow can refresh
related data on the parent window. Events are constrained to the client
environment. Windows in two separate client environments cannot send messages
to each other.
For more information, see “Sending events between windows” on page 262.
Return/Table or
Level Dbl-Clk
Menu/Row Choice
Executes when any of the following actions occur:
A user presses Return (or selects an option button if the field is a selection data
field) in the field specified.
A user double-clicks a row in a table field or selects a row and presses Return to
drill down to the source form. This execution condition works independently of
whether the table drill-down option has been selected for the table field.
A user double-clicks a leaf in a tree view table or selects a leaf and presses Return
to drill down to the source form. (If a user double-clicks on a parent node with
child nodes under it, the node collapses or expands, and no workflow is
executed.)
For more information, see the Form and Application Objects guide.
When a user performs these actions, the active link is executed, and the details of
the record are displayed.
For table fields, this execution condition works only if the user has been granted
permissions to fields on the supporting form, the column fields, and the table field.
Executes when a user selects a choice from a character menu on a field specified in
the Field list or when a user selects a row in a table field or a node in a tree view.
30 Chapter 2—Setting workflow conditions
Workflow Objects
Condition
Description
Gain Focus
Executes when the specified field receives the focus. If you choose this option, the
Field list is enabled so that you can specify the field that will cause the active link to
execute.
Note: If you use the Gain Focus condition to execute an active link on a view field,
the active link might not execute as expected. This is because the HTML page in
the view field is taking the focus.
Lose Focus
Executes as the focus is changed, for example, by clicking in another field. If you
choose this option, the Field list is enabled so that you can specify the field that will
cause the active link to execute.
An existing page field loses focus when a new page of the set appears at the front.
Pages can gain focus whenever a user clicks a tab, an active link sets focus to a page
or a field on a page, or another page is hidden.
Page focus is independent of data field focus.
Note: If you use the Lose Focus condition to execute an active link on a view field,
the active link might not execute as expected. This is because the HTML page in
the view field is taking the focus.
Button/Menu Item
Executes when a user selects the button, menu item, or toolbar button associated
with the active link.
The values in the Field menu are dynamically generated based on the fields from the
form that you select.
Interval
Executes repeatedly on open forms at a specified time interval (15 seconds
minimum, 7200 seconds maximum). All active links at the same interval fire as a
unit, and the execution order applies across those active links. In workflow triggered
by the Interval condition, avoid the use of Message actions and Open Window (of
type Dialog) actions.
Submit
Executes when a request is submitted.
Modify
Executes when a request is modified.
Delete
Executes when a request is deleted.
Get Entry
Executes when a request is retrieved.
Merge
Executes when a request is merged into the database. You cannot merge requests
through BMC Remedy User or the web. You must merge requests by using BMC
Remedy Import, as described in the Configuring guide.
Requests can also be merged by using DSO Independent Copy or the command line
interface (see the Administering BMC Remedy DSO and Integrating with Plug-ins
and Third-Party Products guides).
Workflow conditions 31
BMC Remedy Action Request System 7.0
To refine the selection criteria, enter a qualification statement in the Run If
field.
You can type the qualification or you can build it by using the qualification
bar and field list as described in Chapter 3, “Building qualifications.” When
the qualification is met, the If actions execute; otherwise, the Else actions
execute.
WARNING: Avoid unqualified Run If statements for escalations. Unlike filters
and active links, which are executed by specific operations (for example,
on submit of a request), the only execute condition for escalations is the
time criteria. An unqualified Run If statement for an escalation will
perform an unqualified query to the database and attempt to execute the
actions for every record found in the form. Server performance is
especially degraded for unqualified Run If statements in escalations that
are set to run at intervals. This is due to the server issuing a search to the
database every time the escalation is run, as well as the potential of
numerous searches occurring within short periods of time.
32 Chapter 2—Setting workflow conditions
Chapter
3
Building qualifications
This chapter discusses how to build qualifications for workflow actions. The
following topics are provided:
Qualification basics (page 34)
Fields in qualifications (page 35)
Values in qualifications (page 37)
Status history in qualifications (page 38)
Tips for improving system performance when creating qualifications
(page 39)
Checking transaction versus database values (page 40)
Building qualifications 33
BMC Remedy Action Request System 7.0
Qualification basics
In active links and filters, the qualification statement in the Run If field
determines whether the If actions or Else actions are executed. In escalations,
the qualification statement first identifies the requests to which an escalation
applies. If one or more matching requests is found in the database, escalation
If actions are executed for each matching entry. If no matching requests are
found in the database, escalation Else actions are executed.
As shown in the following figure, you can define qualification criteria by
using any of the following techniques:
Type information directly into the Run If field.
Add a field or keyword from the Run If list.
Add an operator from the qualification bar.
Figure 3-1: Building a qualification in a Filter window
Add operators by selecting
from the qualification bar.
Type directly into the Run
If field.
Use the Run If menu button
to add a field name or
keyword to a qualification.
34 Chapter 3—Building qualifications
Workflow Objects
Qualification statements can contain any valid concatenation of operators,
wildcards, and keywords, as shown in the following examples:
'Submitter' LIKE "Jackson%"
'Create Date' < $TIMETSTAMP$ - (60*60*24)
Appendix A, “Operators, wildcards, keywords, and NULL values,” describes
the meaning for each of these values within AR System.
When entering a qualification, make sure that it is acceptable to the database
on which AR System is running. Avoid creating comparisons with fields of
unlimited length, as the database might not support that capability. For more
information about fields of unlimited length, see the Form and Application
Objects guide.
Note: When creating qualifications for systems running with an MS SQL
Server or a Sybase RDBMS and you enter the qualification in the text entry
dialog box, both databases remove hard returns that are at the end of
character strings. To resolve this problem, AR System adds a space before
any hard return that is at the end of a string. For additional information,
see the Database Reference guide.
The following sections describe the formatting conventions for fields, values,
and status history when constructing qualification criteria.
Fields in qualifications
Quotation
Marks
Enclose field names or their internal IDs in single quotation marks, for
example, 'Short Description' or '7'. If the field name includes a single
quotation mark, specify two single quotation marks when entering the name.
For example, if the field name is Doug's Requests, enter it as 'Doug''s
Requests'. Single quotation marks are automatically added when you select
fields from the Run If list.
For currency fields, you must have one of the following enclosed within
single quotation marks:
The name or ID of the currency field, for example:
'Currency Field' = $NULL$
Fields in qualifications 35
BMC Remedy Action Request System 7.0
The name of the currency field, followed by a period and a specific portion
of the currency field’s value, such as the date or a functional currency
value, for example:
'Currency Field.VALUE' < 5000
Field values
and filters
For filters, you can specify whether the qualification is to reference field
values in the transaction only, in the database only, or in both:
To check the value for the transaction only, enter the field name as
'TR.<field>' (for example, 'TR.Submitter').
To check the value in the database only, enter the field name as 'DB.<field>'
(for example, 'DB.Submitter').
To check the value for the transaction first and then check the database if
a new value is not found in the transaction, enter the field name with no
prefix.
Only new or changed field values are part of a transaction.
The TR and DB prefixes work only in filter Run If qualifications. For more
information, see “Checking transaction versus database values” on page 40.
Field ID 112
and dynamic
group fields
If referencing field ID 112 (for assignee group access) or dynamic group
fields, the value of the field is always in the format of group ID, role ID, or
user name (in single quotation marks). Each group ID, role ID, or user name
is followed by a semicolon. For example, if the name of field 112 is Assignee
Group and the group ID of Sales Staff is 50, you would enter the qualification
as follows:
'Assignee Group' = "50;"
For user Mary Manager, use single quotation marks:
'Assignee Group' = "'Mary Manager';"
To enter multiple groups, roles, and user names in your qualification,
enter a semicolon at the beginning of the list and include no spaces. For
example, the name of field 112 is Assignee Group. To create a qualification
that includes the Sales Staff group (ID 50), the Marketing Staff group (ID
51), the Managers role (ID -90), and user Mary Manager, enter the
qualification using the following specified format:
'Assignee Group' = ";50;51;-90;'Mary Manager';"
36 Chapter 3—Building qualifications
Workflow Objects
You can only use multiple groups for field ID 112 and for dynamic group
fields if your Configuration settings in the Server Information window are
enabled to allow multiple assignee groups. (For more information about
configuration settings, see the Configuring guide.)
Values in qualifications
Some values must be enclosed in quotation marks in a qualification. The
following table outlines when to use quotation marks.
Value
Use
Notes
Quotation
Marks?
Nonnumeric
values
(such as time,
character, and
diary values)
Yes
Enter a date as shown in this example:
"04/01/04"
To search for all requests created after a certain date,
you could enter:
'Create-date' > "04/01/04"
Yes
Nonnumeric
values that
already include
quotation
marks
In addition to the surrounding double quotes,
include an additional double quotation mark. For
example, if you wanted to search for a string such as:
Robert "Bobby" Smith
you would enter:
"Robert ""Bobby"" Smith"
Integers (for
time values)
No
Integers without quotes are interpreted as a number
of seconds. To specify a number of hours, multiply 60
(= 1 minute) * 60 (= 1 hour). For example, to specify
10 hours, enter:
60 * 60 * 10
Values in qualifications 37
BMC Remedy Action Request System 7.0
Value
Use
Notes
Quotation
Marks?
Keywords
No
Enter keywords with dollar signs ($) as shown in this
example:
'Submitter' = $USER$
Using no quotation marks is also enforced for using
keywords with calculations. Valid qualifications
include:
'Create-date' > $TIMESTAMP$
'Create-date' > ($TIMESTAMP$ - (60 * 60 * 24))
Use the keyword $NULL$ to find requests that have no
value in a field (for example, 'Assigned To' = $NULL$).
For qualifications passed to an EXTERNAL() operator,
you can set a character field with a keyword, rather
than with the expanded value of the keyword. Add an
escape character (\) to the qualification, like this:
‘Character Field’ = $\USER$.
The character field will be populated with $USER$
instead of with the user’s name. See “Operator types”
on page 198 for more information about
EXTERNAL().
See “Keywords” on page 203 for available keywords.
Status history in qualifications
Status history references must have the following information and format:
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 is changing the status) or TIME (for the
time that the status changed).
38 Chapter 3—Building qualifications
Workflow Objects
For example:
'Status History.Fixed.TIME' < "07/01/99"
This syntax is created automatically when you select the Status History
reference from the Run If list.
In a filter qualification, you can use a Status History reference if you are
checking values in the database; Status History is not meaningful if you are
trying to check the value of the current transaction. (For more information,
see “Checking transaction versus database values” on page 40.) You cannot
use Status History references in active link Run If qualifications, and you
cannot set the Status History value to a field in an active link set fields action.
Tips for improving system performance when creating
qualifications
When creating qualifications, you can improve system performance
dramatically by avoiding the following searches, which cause a full table scan
of the database:
The != Operator
Searches using the != operator check every record to see if the value is not
contained. If you have created indexes on a field, they will not be used.
Instead, design your qualifications to retrieve what you are looking for,
instead of what you are not looking for. For example, you could rewrite the
searchqualification’Status’!="Closed"to'Status' <"Closed"toimprove
the use of an index.
The != operator does not match entries whose value for the field is NULL.
You must explicitly include a test for NULL to find NULL values. For example,
'Status' != "Closed" will not search for cases where the Status field is empty.
You would have to use the following syntax:
'Status' != "Closed" OR 'Status' = $NULL$
Note: On Sybase databases, you cannot use the != operator against unlimited
character fields where the database input length equals 0.
Tips for improving system performance when creating qualifications 39
BMC Remedy Action Request System 7.0
Wildcards in front of search terms
Searches that begin with a wildcard (for example, 'Submitter' LIKE
"%Jackson%") will not use the index but will scan the database for every
record containing the word Jackson that have any characters preceding the
"J."
Searches with trailing wildcards are valid and use indexes. For example,
'Submitter' LIKE "Jackson%"uses the index and finds all entries starting with
Jackson.
Poorly written arithmetic operations
Searches that use the field in an arithmetic operation can cause a table
scan. For example, a qualification to find all requests greater than 24 hours
($TIMESTAMP$ - 'Create Date' > 60*60*24)will search the entire database for
records with $TIMESTAMP$ (the current date and time). Instead, rewrite the
search qualification to place the indexed field on the left side of the
equation, as in the following: 'Create Date' < $TIMESTAMP$ -60*60*24.
These performance issues apply to escalation Run If qualifications, Set Fields
and Push Fields qualifications, query-style menu qualifications, table field
criteria, and searches from BMC Remedy User or web clients.
These issues do not apply to filter or active link Run If qualifications, which
check the current entry and do not perform a database search.
For escalations, it is critical to system performance that qualifications be
efficient, especially if run on frequent intervals. The qualification should use
indexed fields to narrow the number of requests before an unindexed field
causes an entry-by-entry search. For information about indexing, see the
Form and Application Objects guide.
Checking transaction versus database values
In filter Run If qualifications only (not Set Field or Push Field If
qualifications), the qualification can access values for the current record
from the current transaction or from the database. This makes it possible for
you to check state transitions. For example, you could define a filter that
watches for transactions where the status of a request is changed to Closed.
You can then check the database to verify that the current status of the
request is Fixed, and reject the operation if the status is anything other than
Fixed.
40 Chapter 3—Building qualifications
Workflow Objects
You can specify a field reference in the filter qualification in three ways:
Transaction Only—References the value of the field in the current
transaction only. If the value is not changed in the transaction, it is
considered to be $NULL$. If the operation is a delete, it is considered to be
$NULL$. To specify a check of the transaction only, use the format
'TR.<field>' when you enter the field name in the Run If field.
Database Only—References the value of the field in the database only. No
check is made of the value in the current transaction. If the operation is a
create operation, it is considered to be $NULL$. To specify a reference of the
database only, use the format 'DB.<field>' when you enter the field name
in the Run If field.
Transaction and Database—References the value of the field in the
current transaction and uses that value if changed. If not changed in the
current transaction, references the value of the field in the database. To
specify a reference of both the transaction and the database (in this order),
use the format '<field>' when you enter the field name in the Run If field.
Filter qualification examples
The following procedures outline the steps for creating three different filter
qualifications in the Run If field.
To build a filter qualification for a current transaction
Enter a qualification like the following example:
'TR.Status' = "Fixed" OR 'TR.Status' = "Closed"
This qualification causes the filter to execute when the status of the
transaction is set (or changed) to Fixed or Closed. Note the use of the TR.
syntax, which uses the value as set in the current transaction.
To enter the example qualification using the qualification bar buttons and
menus, complete the following steps:
1 Choose Fields > Status from the Run If list.
The name of the field appears in single quotation marks in the Run If field:
'Status'
2 To cause the filter to act on the current transaction only, type TR. after the
first quotation mark:
'TR.Status'
Checking transaction versus database values 41
BMC Remedy Action Request System 7.0
3 At the end of the qualification, click the equal sign (=) operator in the
qualification bar.
'TR.Status' =
4 Type Fixed enclosed in double quotation marks.
'TR.Status' = "Fixed"
5 Click the OR operator in the qualification bar.
'TR.Status' = "Fixed" OR
6 Repeat steps 1 through 3.
The Run If field now contains:
'TR.Status' = "Fixed" OR 'TR.Status' =
7 Type Closed (enclosed in double quotation marks) to complete your
qualification.
To build a filter qualification on a time basis
Enter a qualification like the following example:
'Status History.New.TIME' < $TIMESTAMP$ - (60 * 60 * 10)
This qualification causes the filter to act on requests that are older than 10
hours. The qualification searches for requests where the time that the request
was created is less than the current time minus 10 hours. This example uses
a status history reference as one of its values.
To enter the example qualification using the qualification bar buttons and
menus, complete the following steps:
1 Enter Fields > Status History > Time > New in the Run If field (where New is the
status value that you want to match and TIME is the keyword for the time
that the request was entered).
'Status History.New.TIME'
2 Click the less than (<) operator in the qualification bar.
'Status History.New.TIME' <
3 Choose Keywords > TIMESTAMP from the Run If list.
'Status History.New.TIME' < $TIMESTAMP$
4 Click the minus sign (–) operator in the qualification bar.
'Status History.New.TIME' < $TIMESTAMP$ -
42 Chapter 3—Building qualifications
Workflow Objects
5 Enter an hour value. (See “Values in qualifications” on page 37 for
information about entering time values.)
To build a filter qualification for a changed field value
Enter a qualification like the following example:
'Status' != 'DB.Status'
This qualification causes the filter to test whether a value has changed in a
field. This example uses the Status field as one of its values.
To enter the example qualification using the qualification bar buttons and
menus, complete the following steps:
1 Choose Fields > Status from the Run If list.
The name of the field appears in single quotation marks in the Run If field:
'Status'
2 With the cursor positioned at the end of the qualification, click the not equal
sign (!=) operator in the qualification bar.
'Status' !=
3 Choose Fields > Status from the Run If list.
'Status' != 'Status'
4 To verify the value of the field in the database, move the cursor to the
beginning of the field name (after the single quotation mark) and enter the
characters DB.
Checking transaction versus database values 43
BMC Remedy Action Request System 7.0
44 Chapter 3—Building qualifications
Chapter
4
Specifying workflow actions
When defining an active link, filter, or escalation action, you must determine
when the action will execute and what the action will be.
The following topics are provided:
If actions and Else actions (page 46)
Creating and modifying actions (page 48)
Types of workflow actions (page 51)
The Call Guide active link or filter action (page 53)
The Change Field active link action (page 54)
The Close Window active link action (page 61)
The Commit Changes active link action (page 62)
The DDE active link action (page 63)
The Direct SQL active link, filter, or escalation action (page 64)
The Exit Guide active link or filter action (page 66)
The Go To Guide Label active link or filter action (page 66)
The Goto active link or filter action (page 66)
The Log to File filter or escalation action (page 68)
The Message active link or filter action (page 69)
The Notify filter or escalation action (page 72)
The OLE Automation active link action (page 78)
The Open Window active link action (page 78)
Specifying workflow actions 45
BMC Remedy Action Request System 7.0
The Push Fields active link, filter, or escalation action (page 97)
The Run Macro active link action (page 106)
The Run Process active link, filter, or escalation action (page 108)
The Set Fields active link, filter, or escalation action (page 112)
The Wait active link action (page 124)
Specifying escalation time criteria (page 124)
If actions and Else actions
An Active Link, Filter, or Escalation window contains an If Action tab and an
Else Action tab. You use the same procedure in both action tabs to create
each action type. What differentiates If actions from Else actions is when they
are processed by AR System.
For each operation (in escalations, based on the defined time interval),
AR System reads the conditions specified in the Basic tab of the Active Link,
Filter, or Escalation window. If the condition is met, the qualification
statement specified in the Run If field is evaluated. Operations where the
qualification is met, will execute the If actions. Operations where the
qualification is not met, will execute the Else actions.
You must define at least one If action per active link, filter, or escalation, and
each can have as many as 25 If actions. Else actions are optional; thus, you can
define none or as many as 25 Else actions. The If and Else tabs numbers how
many actions are defined. The following figure shows three If actions and one
Else action defined in this active link.
46 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-1: Number of If and Else actions shown
In escalations, because Else actions are executed when no requests are found,
Else actions cannot be used to modify a request (that is, Else actions are not
performed on every request in the form that does not match the search
criteria, but are performed once).
Because the escalation qualification determines whether the If actions or the
Else actions of the escalation are executed, it is not possible to run a
combination of the two. AR System executes either the If actions or the Else
actions.
If actions and Else actions 47
BMC Remedy Action Request System 7.0
Creating and modifying actions
Use the following procedures to create, modify, delete, or reorder active link,
filter, and escalation actions.
To create a workflow action
1 Open an active link, filter, or escalation.
See the Getting Started guide for more information.
2 Make sure that the basics and qualifications are specified correctly, according
to the instructions provided on “Defining workflow basics” on page 26.
3 Click the appropriate action tab:
If Action—Executes when the qualification is met.
Else Action—Executes when the qualification is not met.
4 From the New Action list, select the appropriate action type.
Figure 4-2: Active link actions
48 Chapter 4—Specifying workflow actions
Workflow Objects
The window displays the attribute choices for the selected action. See “Types
of workflow actions” on page 51 for an overview of the available action types
for active links, filters, and escalations.
5 Set the attributes for the selected action.
Note: To select a field name for a shared workflow object, remember that
only the field names from the reference form are shown. If you have used
different field names on other forms, you will not see the names listed in
the Action or Basic tabs that define the current workflow object. You can
enter different field IDs from new or other forms, if you are sure that they
are (or will be) valid fields. A warning appears if you enter a field ID that
does not exist on the reference form. You can disable this warning in the
Preferences dialog box. For more information about this warning, see the
Getting Started guide.
6 Click Add Action.
7 To create additional actions, repeat steps 3 through 6 for each new action.
Note: You must select the New Action type each time you create a new action,
even if the action type that you want is currently displayed. Otherwise, you
will modify an existing action.
8 Save your changes.
To modify a workflow action
1 Open an active link, filter, or escalation.
2 Make sure that the basics and qualifications are specified correctly, according
to the instructions provided earlier in this section.
3 Click the If Action tab or the Else Action tab.
4 From the Current Actions list, select the action you want to modify.
See “Types of workflow actions” on page 51 for an overview of the available
action types.
5 Modify the appropriate attributes.
6 Click Modify Action.
Creating and modifying actions 49
BMC Remedy Action Request System 7.0
7 To modify additional actions, repeat steps 4 through 6 for each action.
8 Save your changes.
To delete a workflow action
You can delete all the If actions of a workflow object, provided you create at
least one If action before attempting to save it. However, Else actions are
optional, and you can delete all of them if needed.
1 Open an active link, filter, or escalation.
2 Click the If Action tab or the Else Action tab.
3 From the Current Actions list, select the action to be deleted.
4 Click Delete Action.
A confirmation message appears (if your preferences are set to display a
message, as described in the Form and Application Objects guide).
5 Click Yes.
6 To delete additional actions, repeat steps 3 through 5 for each action.
7 Save your changes.
To change the order of workflow actions
1 Open an active link, filter, or escalation.
2 Click the If Action tab or the Else Action tab.
3 From the Current Actions list, select the appropriate action.
4 Click the up or down Move arrow buttons to move the action up or down in
the action list.
5 To move additional actions, repeat steps 3 and 4 until the actions are in the
correct order.
6 Save your changes.
50 Chapter 4—Specifying workflow actions
Workflow Objects
Types of workflow actions
The table that follows presents the various ways workflow actions can be
defined.
Name
Description
Book or
page
Active
Links
Call Guide
Starts the specified guide.
Change Field
Changes certain characteristics
of a specified field. You can:
Attach a new character menu
to the field.
Move the cursor to the field.
Hide or show the field.
Change the access to the
field.
Refresh table fields.
Change the color of the field
label.
Close Window Closes the current window.
Commit
Changes
Sets the fields in the active
parent form with the data
entered into the dialog box. (If
changes are made on a form
without a dialog box, changes
are made to the database.)
DDE
Executes a DDE operation on a
Windows client.
Direct SQL
Submits an SQL command to a
database, but does not return
data from a database.
Exit Guide
Terminates the current guide
or all the guides running.
Filters
Escalations
page 138
page 54
page 61
page 62
*
Int**
page 64
page 144
* Action is not supported by the web client.
**Int = See the Integrating with Plug-ins and Third-Party Products guide.
Types of workflow actions 51
BMC Remedy Action Request System 7.0
Name
Description
Book or
page
Active
Links
Go To Guide
Label
Causes the guide to continue
after the specified label.
Goto
Executes in an order other than
the normal sequence
determined by the execution
order.
Log to File
Records a request in the audit
trail log file.
Message
Displays an interactive error,
warning, note, prompt, or
accessibility message to the
user.
Sends a notification (email
message or alert) to the
designated user or group.
OLE
Automation
Allows a Windows client to
contact OLE automation
servers to use their
functionality as part of your
application’s overall solution.
Open Window Opens one of the following
windows:
*
Dialog
Search
Submit
Modify
Display
Report
* Action is not supported by the web client.
**Int = See the Integrating with Plug-ins and Third-Party Products guide.
52 Chapter 4—Specifying workflow actions
Escalations
Prompt and accessibility
messages are available for
active links only.
Notify
Filters
page 145
page 66
page 68
page 69
page 72
Int**
page 78
Workflow Objects
Name
Description
Book or
page
Active
Links
Push Fields
Pushes data to a form.
Run Macro
Runs an AR System macro.
Run Process
Runs an independent process
on a client or a server.
Set Fields
Sets field values in the current
request to static or keyword
value, or to values retrieved
from another data source.
Wait
Causes a guide to suspend
execution so that the user has
an opportunity to make a
necessary response.
*
Filters
Escalations
*
page 97
page 106
page 108
page 112
page 146
* Action is not supported by the web client.
**Int = See the Integrating with Plug-ins and Third-Party Products guide.
For filters or escalations, you can also define a Distributed Server Option
action if you are licensed for the Distributed Server Option. For more
information, see the Administering BMC Remedy DSO guide.
The following sections discuss defining workflow actions. Because these
procedures are the same whether you create them in the If Action tab or the
Else Action tab, no distinction is made between the tabs beyond reminding
you to select the appropriate one.
The Call Guide active link or filter action
Use the Call Guide action to start a guide, which is an ordered list of active
links or filters. For more information, see “The Call Guide active link or filter
action” on page 138.
The Call Guide active link or filter action 53
BMC Remedy Action Request System 7.0
The Change Field active link action
Use the Change Field action to dynamically adjust selected characteristics of
fields in the current window. Based on conditions when the active link
executes, you can:
Change the accessibility or visibility of the field.
Change the font style of the field. (This is not supported for tree fields.)
Change the color of the field label or text. (This is not supported for tree
view table fields.)
Change the field label.
Move the keyboard focus (cursor) within the window to the field.
Refresh a table field.
Specify a different menu for a character field.
Define field attributes dynamically (Advanced).
Expand or collapse a tree view table field.
To define the Change Field active link action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Change Field.
The fields required to define the Change Field action appear. The following
figure shows these fields and an example of how a Change Field active link
action might look after you complete the remaining steps in this procedure.
54 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-3: Change Field active link action
3 From the Field Name list, select the name of the field for which you want to
change characteristics.
If you want to use a field other than those that appear in the Field Name
menu, enter the appropriate field ID in single quotation marks, for example,
'640'.
To use a dynamic field name, see step 13 on page 58.
The Change Field active link action 55
BMC Remedy Action Request System 7.0
4 Select the appropriate option from the Field Access list.
To change the current access settings for a tree view table field, button
field, page field, trim field, or menu item, the choices are:
Unchanged
Leaves the access setting as is. (Default)
Enabled
Enables the user to use the field.
Disabled
Prevents the user from using the field.
To change the current access settings for a button field, page field, trim
field, or menu item, the choices are:
Unchanged
Leaves the access setting as is. (Default)
Enabled
Enables the user to use the field.
Disabled
Prevents the user from using the field.
5 To change the visibility of a field, select the appropriate option from the
Visibility list:
Unchanged
Leaves the visibility as is. (Default)
Visible
Makes hidden fields visible.
Hidden
Hides visible fields.
This setting does not change the field definition for the view, it only changes
the appearance in the current screen. The field must be present in the form
view to be made visible. If it is not present on the current view, changing
visibility has no effect.
The Visibility setting is ignored for columns in tree view table fields (but not
for columns in list view table fields).
6 To change the font of the field label, select the appropriate option from the
Field Font list:
Unchanged
Leaves the font as is. (Default)
<font style>
Changes the font to the specified style, such as Edit Field,
Required Field, or Header Text (I). For more information
about fonts, see the Getting Started guide.
56 Chapter 4—Specifying workflow actions
Workflow Objects
7 To change the way a tree view table field is displayed, select the appropriate
option from the Expand/Collapse Tree Levels list:
Unchanged
Leaves the tree view as is. (Default)
Expand All Levels
Displays all levels of the tree view.
Collapse All Levels
Closes all levels of the tree view so that only the root node and
the first level are displayed. If the root node is a level, the tree
is not collapsed.
8 To move the focus (cursor) to the field, select the Set Focus to Field check
box.
9 To refresh the list in a table field, select the Refresh Table Field check box.
10 To change the menu attached to a field, select the Attach Menu to Field check
box, and then select a menu from the list.
You must have a menu assigned to the field before you can change to a
different menu.
The $NULL$ selection allocates space for a menu icon next to the field, but
hides this icon in the user client. When you attach a different menu using the
Change Field action, the menu icon appears without affecting form layout.
For more information, see the Form and Application Objects guide.
11 To change the color of the field label or text, select the Change Label Color
check box, clear the Default Label Color check box, and select a color from
the color palette to specify a color.
To reset the color to its default setting, select the Default Label Color check
box.
12 To change the field label, select the Change Field Label check box and enter
a field label in the Field Label field.
You can enter a specific value, or select a field reference from the list. If you
leave the Field Label field empty, the field label will appear blank.
You can change a column header in a list view table field, but this setting is
ignored for columns in tree view table fields.
The Change Field active link action 57
BMC Remedy Action Request System 7.0
Note: Changing field labels can change the way fields appear in BMC Remedy
User and on the web. For example, long labels might become truncated,
or the field might change position on the form. Leave enough room
around the field to handle the changed label size.
13 To supply a dynamic field name or keyword, select the Advanced check box.
For example, at runtime, you could select the value of a field ID and change
its attribute. For more information, see “Defining advanced change field
action functions” on page 58.
14 Click Add Action (or click Modify Action).
The Change Field action appears in the Current Actions list.
Defining advanced change field action functions
You can define advanced Change Field action functions that provide
enhanced functionality beyond changing attributes of a hard-coded field.
Based on values that workflow or users enter into certain fields, you can
dynamically select fields whose attributes you want to change.
For example, the Change Field form (as shown in Figure 4-4) contains a field
(Dynamic Change Field) that can be hidden or display only. The field ID
value you enter or that is set by workflow determines at runtime the field
whose attributes you want to change, for example, changing the label color
to red. When you click the button that triggers the active link, the Change
Field workflow picks up the field ID and changes the field’s attributes.
Administrators might prefer to hide this functionality from users altogether
and use the Window Loaded execution condition instead.
In this example, if you opened the Change Field form in BMC Remedy User
and entered the field ID for the Short Description field (8) and clicked
Button, the Short Description field label would change from black to red.
58 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-4: Using dynamic workflow to change field attributes
Important: For forms viewed in a browser, do not use a dynamic field ID in
the change field action that makes a field visible; otherwise, performance
will be degraded significantly.
To define advanced Change Field action functions
1 Select Advanced in the Change Field action.
The Field Name field changes to display a list that allows you to enter a field
reference or a keyword. The field reference is from the reference form (for
example, Change Field) that you chose on the Basic tab and is typically
hidden.
The Change Field active link action 59
BMC Remedy Action Request System 7.0
Figure 4-5: Advanced functionality of Change Field active link action
2 In the Field Name field, enter a field (or choose a field or keyword from the
attached menu list) that will dynamically select which field to use.
The attributes of the field ID that a user (or workflow) enters into that field
will be changed when the Change Field action executes.
The field you choose must be in its variable format. For example, if you
choose the field labeled Dynamic Change Field from the Field Name field
list, it would appear as $Dynamic Change Field$, as shown in Figure 4-5.
3 Specify the field attributes that you are changing with this action.
In this example, the field label is being changed to red when the active link
workflow is executed.
4 Click Add Action (or click Modify Action).
The Change Field action appears in the Current Actions list.
60 Chapter 4—Specifying workflow actions
Workflow Objects
The Close Window active link action
Use the Close Window action to close one or more open windows. This
action closes the windows without first saving updated values or pushing
them to the parent window.
If you are using a dialog box, first call the Commit Changes active link action
(page 62) to write the data from the dialog box to the parent form. Then, call
the Close Window action. You specify the values for the parent form fields in
the Open Window active link action (page 78) with the Field Mapping Mode
set to On Close. The Close Window action then returns the focus to the
parent form. For more information, see the Form and Application Objects
guide.
To define the Close Window active link action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Close Window.
Figure 4-6: Close Window active link action
The Close Window active link action 61
BMC Remedy Action Request System 7.0
3 Select or clear the Close All Windows check box. If this check box is:
Selected, all open windows will exit when the active link executes.
Cleared, only the current window the active link is running from will exit
when the active link executes.
4 Click Add Action (or click Modify Action).
The Close Window action appears in the Current Actions list.
The Commit Changes active link action
One major use of the Commit Changes action is to write the data entered in
a dialog box to the parent form. The data is written based on the mapping
you created for the On Close mode in the Field Mapping region of the Open
Window active link action. For more information about the Open Window
active link action, see “The Open Window active link action” on page 78.
When implementing a display-only form as a dialog box, consider adding the
following types of buttons to it:
OK—Uses the Commit Changes and the Close Window active link
actions.
Cancel—Uses the Close Window active link action.
Apply—Uses the Commit Changes active link action.
These buttons are useful in creating custom property sheets (made up of
tabbed dialog boxes) that look like the Preferences dialog box (File >
Preferences) in BMC Remedy Administrator. For more information, see the
Form and Application Objects guide.
If the form is not a dialog box, another important use of the Commit Changes
action is to apply the changes in a form and perform the major form action
(for example, Submit, Search, or Modify).
You can also use the Commit Changes action to save the changes in a request,
for example, when filling out an interactive guide and applying the changes.
62 Chapter 4—Specifying workflow actions
Workflow Objects
To define the Commit Changes active link action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Commit Changes.
Figure 4-7: Commit Changes active link action
3 Click Add Action (or click Modify Action).
The Commit Changes action appears in the Current Actions list.
The DDE active link action
The DDE active link action allows data to be exchanged between a client and
server using DDE. For more information, see the Integrating with Plug-ins
and Third-Party Products guide.
The DDE active link action 63
BMC Remedy Action Request System 7.0
The Direct SQL active link, filter, or escalation action
Use the Direct SQL action to submit any legal SQL command to the database.
The Direct SQL action has a different result than the SQL command you use
to set a field value in the Set Fields action. In the Set Fields action, you use
SQL to query the database for information and then use the returned value
to set a field. With the Direct SQL action, the SQL command is not expected
to return data. For example, you can define a Direct SQL action to perform
inserts or updates to a database.
You must know SQL syntax and concepts to create a Direct SQL action. For
the most effective use of direct SQL commands, you must also have a general
understanding of relational databases and a specific understanding of the
relational database underlying your AR System.
WARNING: Because AR System passes direct SQL commands to the database
without checking the syntax, all commands are submitted to the database.
You must make sure that all submitted commands achieve the desired
result. Your SQL commands should comply with ANSI SQL standards, so
that single quotes are reserved for strings and double quotes are reserved
for use with database object names only.
SQL commands can be generic or specific to the DBMS. What can be
accomplished with Direct SQL commands depends on which DBMS you are
using. If an SQL command is specific to one DBMS, you might not be able to
move the definition to another environment. BMC Remedy does not support
or recommend modifying data in AR System tables, which include data and
definitions. It can result in data corruption.
To define the Direct SQL active link, filter, or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Direct SQL.
The fields required to define the Direct SQL action appear. The following
figure shows these fields and an example of how a Direct SQL active link
action might look after you complete the remaining steps in this procedure.
64 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-8: Direct SQL action
3 From the Server Name list, select AR System server where you want to run
the SQL command.
4 In the SQL Command field, enter the command that you want to submit to
the database.
You must enter the entire SQL command in this field. The previous figure
illustrates how you can open a dialog box to enter a lengthy direct SQL
command that will select all entries in the specified form and sort them in
ascending order.
5 Click Add Action (or click Modify Action).
The Direct SQL action appears in the Current Actions list.
For more information, see “Performing the SQL operation” on page 218.
The Direct SQL active link, filter, or escalation action 65
BMC Remedy Action Request System 7.0
The Exit Guide active link or filter action
Use the Exit Guide action to terminate the current guide and, optionally, all
of its calling guides.
For more information, see “The Exit Guide active link or filter action” on
page 144.
The Go To Guide Label active link or filter action
Use the Go To Guide Label action to redirect the flow of execution within a
guide to a specific active link or filter. For more information, see “The Go To
Guide Label active link or filter action” on page 145.
The Goto active link or filter action
Use the Goto action to execute an active link or filter in an order other than
the normal sequence determined by the active link or filter execution order.
When a Goto action executes, the first item with an execution order greater
than or equal to the number that you specify will execute next. You can
specify a static or variable execution order value.
This action can be useful when you want to execute a sequence multiple
times. For each time that you want to execute an active link or filter, a Goto
action returns you to the active link or filter with which you want to begin.
To define the Goto active link or filter action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Goto.
The fields required to define the Goto action appear. The following figure
shows these fields and an example of how a Goto action might look after you
complete the remaining steps in this procedure.
66 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-9: Goto active link action
3 Specify the appropriate execution order:
To specify a static execution order value, select the Execution Order
option, and type the appropriate execution order in the Goto Execution
Order field.
You can specify an execution order of as many as 4 digits. If you specify an
execution order of 0, the first active link that meets the execution
conditions will execute. If you specify an execution order that is greater
than or equal to 1001, you jump to the end of the processing, and no more
active links or filters execute for this condition.
To specify a variable execution order value, select the Execution Order
From Field Value option button. Then, from the Field With Execution
Order list, select the field where you want the active link or filter to look
for the appropriate execution order (only integer fields are listed).
4 Click Add Action (or click Modify Action).
The Goto action appears in the Current Actions list.
The Goto active link or filter action 67
BMC Remedy Action Request System 7.0
The Log to File filter or escalation action
Use the Log to File action to append all operations meeting the filter or
escalation conditions to a text file on the AR System server. Each log entry
includes:
A date and time stamp.
The name of the user whose action triggered the filter.
The name of the form.
The request ID number.
The fields included in the transaction.
Escalations support Log to File If actions, but do not support Log to File Else
actions.
Note: If a failure occurs when writing to the log file that you specify,
AR System records a warning message in the arerror.log file. This
warning message appears only once, not for every time logging fails. The
next time the system successfully writes to the log file that you specified, a
message is also written to the arerror.log file.
To define the Log to File filter or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Log to File.
The File Name field appears.
68 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-10: Log to File filter action
3 In the File Name field, enter the full directory path of the file to which you
want to log in.
4 Click Add Action (or click Modify Action).
The Log to File action appears in the Current Actions list.
The Message active link or filter action
Use the Message action to display an interactive error, warning, note, or
message for any operation that meets the active link or filter conditions.
To define the Message active link or filter action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Message.
The fields required to define the Message active link or filter action appear,
as shown in the following figure.
The Message active link or filter action 69
BMC Remedy Action Request System 7.0
Figure 4-11: Message active link action
3 In the Text field, enter the text of the message.
You can enter an unlimited number of characters for active links and a
maximum of 255 characters for filters. You can use the Text field list to insert
fields from the current form or keywords (see “Keywords” on page 203). The
field or keyword will be expanded when the message is sent.
Click the text edit button to open a Text dialog box for easier data entry and
to include hard returns in the message.
4 From the Type list, select the appropriate message type.
The message type is displayed as a label with the message. The available
message types are:
Note
Displays a note and continues the operation. The message is labeled
ARNOTE.
Warning
Displays a warning and continues the operation. The message is
labeled ARWARN.
70 Chapter 4—Specifying workflow actions
Workflow Objects
Error
Displays an error and terminates the operation. No actions are
performed after an error message. For example, you can use an
error message to disallow requests with no value in a specific field,
even if the field is not normally a required field. The message is
labeled ARERR.
Prompt
Active links only. Displays a message in the Prompt Bar and
continues.
Accessible
Active links only. In web clients, displays a message that can be
interpreted by a screen reader for a visually impaired user. The
message only appears when both of the following user preferences
are set:
Accessible Mode—Screen Reader/No Vision.
Accessible Message—Message Action or All Actions.
Note: The All Actions setting also displays accessibility messages for
visual changes caused by change field and set field active link
actions.
For more information about accessibility, see the Installing and
Administering BMC Remedy Mid Tier guide and BMC Remedy
User help.
5 For active links only, select the Show Message in Prompt Bar check box if you
want the message to appear in the Prompt Bar and the operation to be
continued.
If the Prompt Bar is hidden, one of the following events occurs:
When a guide is running, the Prompt Bar becomes visible for the duration
of the guide when a Wait or a Message action causes anything to happen
in the Prompt Bar.
When no guide is running and you define an error, warning, or note, the
message appears in a dialog box.
When using this action on the web, all messages appear in a dialog box,
except for prompt messages, which appear in the browser’s status bar.
WARNING: A message of note, warning, or error that is sent to the Prompt
Bar can be overwritten by other prompt messages, and by the field help
when the field focus changes. For this reason, select the Show Message in
Prompt Bar check box only if you are including the message in a guide or
for special applications.
The Message active link or filter action 71
BMC Remedy Action Request System 7.0
6 In the Number field, enter a message number.
The message number is displayed with the message. The number that you
specify must be greater than or equal to 10000. (Numbers less than 10000 are
reserved for AR System messages.) Message numbers are not displayed with
Prompt messages.
You should select unique numbers for different messages. These messages
can be added to the Error Messages form to provide a complete list of
AR System messages and your specific messages, or to the Message Catalog
form to allow for localization of the Message text.
7 Click Add Action (or click Modify Action).
The Message action appears in the Current Actions list.
The Notify filter or escalation action
Use the Notify action to send specified users or groups an email, an alert, or
a notice using another mechanism. For example, you could create a filter that
notifies support staff that they have been assigned a new request. Alerts are
stored in the database, and users can view them in BMC Remedy User or in
a browser in an alert list.
For more information about the alert system and alerts on the web, see the
Configuring guide.
To define the Notify filter or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Notify.
The fields required to define the Notify filter or escalation action appear. The
following figure shows these fields and an example of how a Notify action
might look after you complete the remaining steps in this procedure.
72 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-12: Notify filter or escalation action
3 In the Text field, enter the text of the message.
For Email notifications, the limit to the amount of text you can include is
32 KB. If the notification mechanism is Alert, enter no more than 255
characters in the Text field—the maximum amount of text that can be
retrieved in the alert list.
You can use the Text list to insert fields from the current form or keywords
into the text (see “Keywords” on page 203). The field or keyword will be
expanded when the notification is sent, to a maximum of 32 KB. Click the
text edit button to open a Text dialog box for easier data entry and to include
hard returns in the message.
4 In the User Name field, enter the name of the users or groups to notify.
You can enter a maximum of 255 characters. Use the User Name list to insert
fields or keywords. Click the text edit button to open a Text dialog box for
easier data entry.
The Notify filter or escalation action 73
BMC Remedy Action Request System 7.0
To specify one or more recipients, enter any of the following choices
separated by hard returns (the server evaluates each line separately):
AR System user logins
AR System groups
This option enables you to send notifications to all members of a group
simultaneously. When you include a group in a notification, you are not
notifying the group itself but rather the individuals in the group. The
group name expands the notification to each individual. Do not put the
group name in dollar signs ($) or in quotation marks.
Do not use group notifications as an email system for broadcast items
because the server processes a notification for each member. An email
alias is more efficient.
Direct email addresses
Use this option if you notify by email. Include the email domain name if
you are entering a user’s name (for example, [email protected]) or a
keyword (for example, [email protected]).
A field reference
You can enter a field name or ID within dollar signs ($) to indicate that the
name of the user (or group) to notify is in a field in the request. For
example, to send a message to the user who created the request, you would
enter $Submitter$. A field is processed in the same way as a user name. A
field can contain one or more people of any of the first three categories.
Separated by hard returns, the field cannot contain another field
reference.
Do not include the domain name as part of the notification if you are
using a field reference (for example, enter only $Submitter$) because the
email address is being read from the Email Address field of the user’s entry
in the User form. For more information about users and the User form,
see the Configuring guide.
74 Chapter 4—Specifying workflow actions
Workflow Objects
Note: AR System resolves the contents of the User Name field by first
checking for a matching request in the User form. If found, the
notification is sent to that user. If not found, the server checks for a
matching request in the Group form. If the name corresponds to a group
name, the notification is sent to all members of that group. If no User or
Group definition is found, the contents of the User Name field are used as
is and treated as a guest user of the system.
5 Use the Priority field when the notification is sent as an alert.
Enter a value that can range from 0–10. The priority is entered into the
Priority field of the Alert Events form. The user can then sort the alert list by
the priority value.
6 From the Mechanism field, select a notification mechanism for the message.
Mechanism
Description
Alert
The specified users are notified with entries in the Alert Events
form. Users can view their list of alerts and open the originating
requests in BMC Remedy User or on the web. For more
information about the alert system and alerts on the web, see the
Configuring guide.
For more information about BMC Remedy Alert, see BMC
Remedy User Help and BMC Remedy Alert Help.
Email
The specified users are notified by email. 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, or
MAPI mail protocols. This address can be an email address
representing users who are not using AR System, an alias for a
group, or an email address representing a program.
If you choose the Email option, the Shortcut options appear, and
Messages and Templates tabs appear.
See step 7 for information about the Shortcut options.
The Message and Template tabs are optional, and can be used to
override default parameters relating to the email system. For
more information, see the Administering BMC Remedy Email
Engine guide.
The Notify filter or escalation action 75
BMC Remedy Action Request System 7.0
Mechanism
Description
User Default
The specified users are notified using the default method
specified in their User form record. If the User record does not
contain a default mechanism, the user is notified through BMC
Remedy Alert. If this mechanism fails, the notification is not
delivered.
If you choose the User Option option, the Add Shortcut check
box appears. Select this check box to include the originating
request as an ARTask attachment if their default mechanism is
email.
Cross-Reference The specified users are notified using the mechanism specified by
an integer or selection field in the form. Users are notified based
on the field value in the current request. If you choose this
option, use the Reference Field menu to select the field to use.
Here are the meanings of each numeric value (the first item in a
selection field has a value of 0):
Other
0
Do not notify
1
Alert
2
Email
3
User Default
The specified users are notified using the mechanism specified in
the Other Code field. If you choose this option, enter a numeric
value between 4 and 98 in the Other Code field to indicate the
mechanism to use. This writes the message to the file
<ar_install_dir>\arserver\db\notification<nn>.arn
, where <nn> is the number that you entered. (For UNIX, the
path is <ar_install_dir>/db/notification<nn>.arn.)
Writing notifications to a file enables you to create your own
delivery daemon (UNIX) or service (Windows). For example,
you could set up your system to page users when they receive a
notification. (Specifying 0 through 3 uses the mechanisms in the
“Cross Reference” description.)
If the mechanism is Email, User Default, Cross Reference, or Other, the
Subject Line field becomes enabled so that you can enter text that will appear
in the subject line of the notification.
76 Chapter 4—Specifying workflow actions
Workflow Objects
7 If you select Email, select the appropriate Shortcut options to add a shortcut
in the email that is sent:
ARTask—Includes a link to the request, which will open the request in
BMC Remedy User.
Web URL—Includes a URL to the request, which will open in a browser.
This URL is defined in the Email Notifications Web Path field, which is
located on the Advanced tab of the Server Information window. See the
Configuring guide for more information.
If neither of the two shortcut options is selected, a shortcut will not be sent
in the email notification.
8 If applicable, type subject text for the notification in the Subject Line field.
You can enter a maximum of 255 characters. You can use the Subject Line
field menu list to add fields or keywords to the text (see “Keywords” on
page 203). 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 click the text edit
button to open a Text dialog box for easier data entry.
For UNIX systems, you can include extra header lines in your email message
by inserting hard returns followed by formatted mail headers in the Subject
Line field. The resulting notification will contain a Subject Line and your
header lines. However, the total of all data in the Subject Line field must be
255 or fewer characters.
9 Except for the Alert mechanism, use the Include Fields list to select which
fields have content you want sent in the notification (in addition to the
notification text).
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.
To be able to send the field contents, make sure that users being notified have
permissions to view the contents.
The Notify filter or escalation action 77
BMC Remedy Action Request System 7.0
The field data will be ignored when the notification is delivered if one of the
following conditions is true:
The mechanism is User Default, and the User record specifies that BMC
Remedy Alert is the default mechanism.
The mechanism is Other, and the Other Code is 1 (Alert).
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.
To guarantee the order of fields in a notification, you can create a special view
named ARNotification. (Make sure that you exclude any page fields from
this view.) Otherwise, notifications will default to the default view. If there is
no default view, the first view listed is used.
10 Click Add Action (or click Modify Action).
The Notify action appears in the Current Actions list.
The OLE Automation active link action
Use the OLE Automation action to share functionality between applications
that support OLE. For more information, see the Integrating with Plug-ins
and Third-Party Products guide.
The Open Window active link action
Use the Open Window action to open different types of windows in
AR System, for example, a modal dialog box from a parent form or a submit
window.
Window types include the following categories:
Dialog boxes (see “To define the Open Window active link action for
dialog boxes” on page 79)—The Open Window action defines what data
is transferred from the parent form to the dialog box when the dialog box
opens, and what data is transferred from the dialog box back to the parent
form when the dialog box closes.
78 Chapter 4—Specifying workflow actions
Workflow Objects
Data transfer from the parent form to the dialog box is automatic and
based on the field mapping you create for the On Open mode in the
Field Mapping region.
Data transfer from the dialog box back to the parent form is not
automatic. You must create a Commit Changes active link action (see
“The Commit Changes active link action” on page 62) that executes
before or when the dialog box closes to cause data transfer. Data
transfer is based on the field mapping you create for the On Close mode
in the Field Mapping region.
For more information, see the Form and Application Objects guide.
Search or Submit (see “To define the Open Window active link action for
Search or Submit windows” on page 82)—The Open Window action
opens the form in Search or Submit mode and then populates the form
with the input field/value data you have specified.
Modify or Display (see “To define the Open Window active link action for
Modify or Display windows” on page 84)—The Open Window action
opens the form in Modify or Display mode. You specify search criteria to
define the set of entries to be displayed when the window opens.
Report (see “To define the Open Window active link action for Report
windows” on page 88)—The Open Window action opens the form in
Report mode. You specify search criteria to define the set of entries to be
displayed when the window opens.
To define the Open Window active link action for dialog boxes
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Open Window.
3 From the Window Type list, select Dialog.
The fields required to define the Open Window action for dialog boxes
appear. The following figure shows these fields and an example of how an
Open Window active link action might look after you complete the
remaining steps in this procedure.
The Open Window active link action 79
BMC Remedy Action Request System 7.0
Figure 4-13: Open Window active link action (dialog boxes)
4 Select the Server Name, Form Name, and Form View for the form that you
want to open as a dialog box.
For a group of users, you can create an alternate view of an existing view that
can dynamically open at run time. The alternate view must start with the
same prefix as an existing view. For example, if an existing view has the label
Inventory, an alternate view could have the label Inventory_Large Font.
Select Inventory in the Form View field of the active link, and instruct users
to specify _Large Font in the Open Window View Extension field in user
preferences.
If no form view is entered in the Form View field of the active link, the default
view will be used. For information, see the Form and Application Objects
guide.
80 Chapter 4—Specifying workflow actions
Workflow Objects
5 Select the appropriate option from the Mode list:
On Open
Maps where data from the parent form will transfer to the dialog
box when the dialog box opens. The Field Name column lists the
fields in the dialog form.
On Close
Maps where data from the dialog box will transfer to the parent
form when the dialog box closes. The Field Name column lists the
fields in the parent form.
For each field for which you want to create a mapping, right-click in the
Value column to display a list from which you can select field values,
keywords, or functions. You can also enter default text or numbers.
You can map as many or as few fields between the dialog box and the parent
form as you want.
Note: You are responsible for your own data conversion in these mappings;
BMC Remedy Administrator does not automatically validate them. You
can map fields of different types, and conversion still occurs.
6 Select or clear the Show Close Button in Dialog check box. If the check box is:
Selected—A close box appears in the upper-right corner of the dialog box
in BMC Remedy User. (For forms viewed on the web, the Show Close
Button in Dialog check box is ignored because browsers always contain an
X [close] button in the top right corner.)
Cleared—A close box does not appear. You must create a Close Dialog
action to close the dialog box and return the focus to the parent form.
The Open Window active link action 81
BMC Remedy Action Request System 7.0
Note: When developing a dialog box, create buttons that predictably exit the
dialog box and accomplish the actions that you want to occur.
For example, to save the changes made in the dialog box and then close the
dialog box, you should create an OK button on the dialog box. Then create
an active link that executes when the OK button is clicked and that
commits the changes and closes the dialog box. You could also create a
Cancel button that closes the dialog box without saving the changes. If you
do not create these buttons, the only way that the user can exit the dialog
box is by clicking the x icon in the top right corner of the dialog box.
Clicking the x icon results in unsaved changes and can result in other
workflow actions that do not occur.
7 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Open Window action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the forms on the
server.
8 For additional Open Window options, click Advanced.
These options let you dynamically define which server, form, and view will
open the window. For more information, see “Using advanced Open
Window action functions” on page 94.
9 Click Add Action (or click Modify Action).
The Open Window action appears in the Current Actions list.
To define the Open Window active link action for Search or Submit
windows
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Open Window.
3 From the Window Type list, select Search or Submit.
The fields required to define the Open Window action for a search or submit
window appear. The following figure shows these fields and an example of
how an Open Window active link action might look after you complete the
remaining steps in this procedure.
82 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-14: Open Window active link action (search or submit windows)
4 From the Target Location list, select one of the following options:
New—Opens form in a new window.
Current—Opens form in current window. (For web clients only)
You can also enter a frame name, which opens the form inside the frame.
In the case of a view field frame, the name is VF<FieldId>; for example,
FV536870913. (For web clients only)
5 Select the Server Name, Form Name, and Form View for the form that you
want to open as a search or submit window.
For a group of users, you can create an alternate view of an existing view that
can dynamically open at run time. The alternate view must start with the
same prefix as an existing view. For example, if an existing view has the label
Inventory, an alternate view could have the label Inventory_Large Font.
Select Inventory in the Form View field of the active link, and instruct users
to specify _Large Font in the Open Window View Extension field in user
preferences.
The Open Window active link action 83
BMC Remedy Action Request System 7.0
If no form view is entered in the Form View field of the active link, the default
view will be used. For information, see the Form and Application Objects
guide.
6 To set the fields to their default values when the window is opened, select the
Set Fields to Default Values check box.
7 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Open Window action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the forms on the
server.
8 For additional Open Window options, click Advanced.
These options let you define dynamically which server, form, and view will
open the window. For more information, see “Using advanced Open
Window action functions” on page 94.
9 Click Add Action (or click Modify Action).
The Open Window action appears in the Current Actions list.
To define the Open Window active link action for Modify or Display
windows
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Open Window.
3 From the Window Type list, select Modify or Display.
The fields required to define the Open Window action for a modify or display
window appear. The following figure shows these fields and an example of
how an Open Window active link action might look after you complete the
remaining steps in this procedure.
84 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-15: Open Window active link action (modify or display windows)
4 Choose a Display Type:
List Only—Displays a list of results. An individual entry will be opened
when a user clicks on an item from the list.
In forms viewed on the web, the results are shown in a split display.
Detail Only—Displays the Detail window with Next and Previous
buttons.
In forms viewed on the web, the first matching entry is displayed. No
toolbar buttons are available to move between entries, but you can add
Next and Previous buttons and support them with workflow.
Split Window—Displays a split window, the top half with a list of entries,
and the bottom half with an entry displayed.
Clear—Uses the display type specified by the Show Result List Only user
preference.
In forms viewed on the web, the results are shown in a split display.
The Open Window active link action 85
BMC Remedy Action Request System 7.0
5 From the Target Location list, select one of the following locations where you
want the window to appear:
New—Opens form in a new window.
Current—Opens form in current window. (For web clients only)
You can also enter a frame name, which opens the form inside the frame.
In the case of a view field frame, the name is VF<FieldId>; for example,
FV536870913. (For web clients only)
You can also use a field reference that dynamically defines the target at
runtime. You must supply a correct field reference that contains a valid value
for the target. Valid values for the Target identifier are:
to-screen:
to-print:
to-file:
Include a space after the colon. For example, to create a screen target based
on a field reference, the value in the field you select would contain
to-screen: .
6 Select the Server Name, Form Name, and View Name for the form that you
want to open as a modify or display window.
For a group of users, you can create an alternate view of an existing view that
can open dynamically at run time. The alternate view must start with the
same prefix as an existing view. For example, if an existing view has the label
Inventory, an alternate view could have the label Inventory_Large Font.
Select Inventory in the Form View field of the active link, and instruct users
to specify _Large Font in the Open Window View Extension field in user
preferences.
If no form view is entered in the Form View field of the active link, the default
view will be used. For information, see the Form and Application Objects
guide.
86 Chapter 4—Specifying workflow actions
Workflow Objects
7 In the Qualification tab, complete the following steps:
a Define a qualification that will find the entries you want returned when
the window opens. You can type the qualification, or you can build it by
using the qualification bar and list, as described in Chapter 3, “Building
qualifications.”
b From the If No Requests Match box, select a handling option to control
how BMC Remedy User or the web client responds when no matches are
found in the selected form:
Do Not Show Any Message—No message appears regardless of results
returned.
Show Default Message—Standard system-generated message appears
if no requests match.
Show Message—The message that you define in the Message tab
appears.
c Optionally, select Suppress Empty List to specify that an empty list will not
appear if no results are returned from the search.
8 To display a note, warning, and error:
a Click the Message tab.
b In the Text field, enter the text of the message.
c From the Type list, select the appropriate message type.
d In the Number field, enter a message number.
For more information about these parameters, see “The Message active link
or filter action” on page 69.
9 In the Sort Info tab, set the options for sorting the requests:
a From the drop-down lists, select up to five fields that you want to sort by.
All the fields on the form that you can sort by are displayed in the list.
b For each field you choose, select whether the field is to be sorted in
ascending or descending order.
c In the Polling Interval field, specify how often (in minutes) you want the
search to be reissued.
This option enables you to reissue the search on the new window
automatically in BMC Remedy User. This feature is not supported for web
clients.
The Open Window active link action 87
BMC Remedy Action Request System 7.0
10 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Open Window action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the forms on the
server.
11 For additional Open Window options, click Advanced.
These options let you dynamically define which server, form, and view will
open the window. For more information, see “Using advanced Open
Window action functions” on page 94.
12 Click Add Action (or click Modify Action).
The Open Window action appears in the Current Actions list.
To define the Open Window active link action for Report windows
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Open Window.
3 From the Window Type list, select Report.
The fields required to define the Open Window action for a report window
appear. The Report Information tab is enabled, as shown in the following
figure.
88 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-16: Open Window active link action (report windows)
4 From the Target Location list, select one of the following locations where you
want the window to appear:
New—Opens report in a new window.
Current—Opens report in current window. (For web clients only)
You can also enter a window name or HTML frame name. If a window with
that name does not exist, a new window opens with the name you specify.
You can also use a field reference that dynamically defines the target at
runtime. You must supply a correct field reference that contains a valid value
for the target. Valid values for the Target identifier are:
to-screen:
to-print:
to-file:
The Open Window active link action 89
BMC Remedy Action Request System 7.0
Include a space after the colon. For example, to create a screen target based
on a field reference, the value in the field you select would contain
to-screen: .
5 Select the Server Name, Form Name, and View Name for the form on which
you want to run a report.
For a group of users, you can create an alternate view of an existing view that
can open dynamically at run time. The alternate view must start with the
same prefix as an existing view. For example, if an existing view has the label
Inventory, an alternate view could have the label Inventory_Large Font.
Select Inventory in the Form View field of the active link, and instruct users
to specify _Large Font in the Open Window View Extension field in user
preferences.
If no form view is entered in the Form View field of the active link, the default
view will be used. For more information, see the Form and Application
Objects guide.
6 In the Qualification tab, perform the following steps:
a Define a qualification that will find the entries you want included in the
report. You can type the qualification, or you can build it by using the
qualification bar and list, as described in Chapter 3, “Building
qualifications.”
b For AR System reports only, from the If No Requests Match box, select a
handling option to control how BMC Remedy User or the web client
responds when no matches are found in the selected form:
Do Not Show Any Message—No message appears regardless of results
returned.
Show Default Message—Standard system-generated message appears
if no requests match.
Show Message—The message that you define in the Message tab
appears.
For Crystal reports, only the Do Not Show Any Message option is
recognized.
c Do not select Suppress Empty List.
This option is not relevant for reports.
90 Chapter 4—Specifying workflow actions
Workflow Objects
7 For AR System reports, set the options for sorting the requests in the Sort
Info tab. (The settings in this tab are ignored for all other report types.)
a From the drop-down lists, select up to five fields that you want to sort by.
All the fields on the form that you can sort by are displayed in the list.
b For each field you choose, select whether the field is to be sorted in
ascending or descending order.
c In the Polling Interval field, specify how often (in minutes) you want the
search to be reissued.
This option enables you to reissue the search on the new window
automatically in BMC Remedy User. This feature is not available for web
clients.
8 Click the Report Information tab (see Figure 4-16 on page 89), and perform
the following steps.
a From the Report Type list, select a report type.
Other report options might appear, depending on which report engine
software you have installed on your system.
You can also use a field reference that dynamically defines the report type
at runtime. The field reference must contain a valid value, which includes:
The Report Type identifier (21=).
The corresponding numeric report type (1 for AR System and 2 for
Crystal).
For example, to create an AR System report based on a field reference, the
value in the field you select would contain 21=1.
b From the Location list, select where the report resides:
Embedded—Report resides on the server in a support file.
Local—Report resides on local disk.
Reporting Form—Report resides on the reporting server in the Report
form. The Reporting Form location is only available when using
centralized user preferences and when the report server is defined in the
BMC Remedy User Preference form. The Report form has a unique
index, which guarantees that the report name is unique.
c In the Name field, enter the full path name for your report (for example,
C:\temp\report2.rpt).
The Open Window active link action 91
BMC Remedy Action Request System 7.0
If the report is located on a network, map a drive to that location and
include the drive letter in the path name (for example,
V:\shared\report2.rpt).
For embedded reports, the path name must be for a location on, or
accessible to, the BMC Remedy Administrator client machine. This
allows AR System to store the report with the Open Window action
when you save the active link.
For local reports, the path name must be for a location on, or accessible
to, the user client machine. This allows AR System to run the report
from the client machine when the Open Window action executes.
For Reporting Form reports, enter the name of the report as entered in
the Name field of the appropriate entry in the Report form.
d To save an embedded report to another area on the network, enter the
report name and click the Save To Disk button.
This step is crucial if you want to modify the active link on another
machine where the embedded report does not reside locally. Click the Save
to Disk button before you attempt to save the Open Window active link.
Otherwise, you will lose the embedded report.
Note: Embedded reports are saved with the active link (that is, the report is
appended to the active link definition). If you make changes to the report
after creating the active link, save the active link to use the updated report.
e For web clients only, select a field reference in the Entry IDs field list that
will pass the ID numbers of the entries selected for the report in the Query
List View.
If there is more than one entry ID, separate them with commas.
These IDs will take precedence over any search entered in the
Qualification tab. However, if the Entry IDs field is blank, the qualification
criteria will be used to create entries for the report.
f From the Destination drop-down list, select where you want your report
to appear:
Screen
Printer
File
92 Chapter 4—Specifying workflow actions
Workflow Objects
For web reports, you must choose Screen.
You can also use a field reference that dynamically defines the destination
at runtime. You must supply a correct field reference that contains a valid
value for the destination. Valid values for the Destination identifier are:
to-screen:
to-print:
to-file:
Include a space after the colon. For example, to create a screen destination
based on a field reference, the value in the field you select would contain
to-screen: .
g For web clients, if your third-party report engine supports query override,
enter Yes or No in the Query Override field to indicate whether you want
the query in the results list or table field to override the query stored in the
report.
Make sure that the Query Override field in the Report form is consistent
with the Query Override in this Open Window active link so that the
report will run correctly at runtime.
h For web clients, select Run from the Operation list to run a report by using
the Start command in the ReportType entry for the selected report type.
Note: In the pre-6.3 mid tier, you used Create and Edit operations for Open
Window active link actions with a Window Type of Report to create and
modify AR System reports. In the 6.3 and later versions of the mid tier,
Create and Edit operations are not supported. To create and edit reports
from an Open Window active link, use the Submit Window Type, and
select the ReportCreator form.
If any of these commands is empty in the ReportType entry, the
corresponding operation will produce a runtime error.
9 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Open Window action only to the forms in the
application.
Clearing the Restricted List check box lets you access all the forms on the
server.
The Open Window active link action 93
BMC Remedy Action Request System 7.0
10 For additional Open Window options, click Advanced.
The Advanced options let you dynamically define which server, form, and
view will open at runtime. If the Advanced check box is selected, all of the
fields on the Report Properties tab and in the Server Name, Form Name, and
Form View fields can have field references. For more information, see “Using
advanced Open Window action functions” on this page.
11 Click Add Action (or click Modify Action).
The Open Window action appears in the Current Actions list.
Using advanced Open Window action functions
You can define advanced Open Window action functions that provide
enhanced functionality beyond opening a window from a specific
hard-coded server, form, and view defined in the workflow action. You can
dynamically change which server, form, and view the window opens against
based on certain field values that are set by workflow, a data-dictionary
menu, or user entry.
For example, the Report Window form (as shown in Figure 4-17) contains
three fields (server, form, and view) that can be hidden or display-only. The
values you enter into these fields (for example, from a Set Fields action)
determine at runtime which source server, form, and view are used as sources
in the Open Window action.
When you click the button that triggers the active link, field values in the
Report Window form on the source server (polycarp) open the form and its
view on the destination server (cordova). Administrators might prefer to
hide this functionality from users altogether and use the Window Loaded
execution condition instead.
94 Chapter 4—Specifying workflow actions
Workflow Objects
Figure 4-17: Using dynamic workflow to open windows
In this example, if you opened form Report Window in BMC Remedy User
and entered cordova as the server and Target as the form, then clicked
Button, the advanced Open Window action is triggered. The server and form
(and view if specified) have become dynamically defined in the Open
Window workflow and the Target form opens in Submit (New) mode.
To use advanced Open Window action functions
1 Click Advanced.
The window changes in the following ways:
The Server Name, Form Name, and Form View fields have boxes that
allow you to enter field references or keywords for the server, form, and
view names. These fields come from the reference form (for example,
Report Window) that you chose on the Basic tab and are typically hidden.
The Open Window active link action 95
BMC Remedy Action Request System 7.0
The Sample Server Name and Sample Form Name fields appear (as shown
in Figure 4-18). Default values listed are the current server and form. You
use these “sample” fields to complete the Custom or Matching IDs field
mapping section of the Open Window action. The “sample” form must
contain fields that exist on any dynamic source forms that are used at
runtime. But the sample server and form are not actually used at runtime;
the fields you pick are only used to build the workflow.
Figure 4-18: Advanced functionality of Open Window–Dialog active link action
2 In the Server Name, Form Name, and Form View fields, enter a field or
keyword that will dynamically select which server, form, and view to use.
You must enter values into the Server Name and Form Name fields. (The
Form View setting is optional.) The server, form, and view you choose will
appear in their variable format. For example, if you choose server from the
Server Name field list, it appears as $server$, as shown in Figure 4-18.
96 Chapter 4—Specifying workflow actions
Workflow Objects
The server and form a user (or workflow) enters into those fields will be used
to populate the form when the Open Window action executes.
3 From the Sample Server Name and Sample Form Name lists, select the
reference server and form that will function as the “sample” form that will be
opened with the Open Window action.
The value menu is populated with fields from the “sample” form. Select field
values that correspond to fields available on any dynamically selected form at
runtime.
The “sample” server and form are used as a temporary reference to create and
save the Open Window workflow. You can even delete the sample form after
saving the action.
4 Depending on the window type you selected, edit the field mappings or
qualifications accordingly.
For example, if you selected Submit window type, enter mappings for fields
and their values (entering the keyword $USER$ as the value for the Submitter
field). These values will then appear when the “sample” window is opened
(the login user’s name appears when the Submit window opens).
5 Click Add Action (or click Modify Action).
The Open Window action appears in the Current Actions list.
The Push Fields active link, filter, or escalation action
Use the Push Fields action to transfer values from selected fields in the
current request to another request. This enables you to automate updates to
the database.
You can push values from tables, hidden fields, fields not in the active view,
or fields in no views at all. However, you cannot push values to non-data
fields like table fields, column fields, page holders, and view fields.
(To move data to the current request from a variety of data sources, see “The
Set Fields active link, filter, or escalation action” on page 112.)
To define the Push Fields active link, filter, or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Push Fields.
The Push Fields active link, filter, or escalation action 97
BMC Remedy Action Request System 7.0
The fields required to define the Push Fields active link, filter, or escalation
action appear. The following figure shows these fields and an example of how
a Push Fields active link action might look after you complete the remaining
steps in this procedure.
Figure 4-19: Push Fields active link action
3 From the Server Name list, select the server source that contains the form and
field to which you want to push data.
For active links, you can select a server to which you are logged in from the
field list, or you can type in the name of any server on the network.
For filters or escalations, you can select only the current server.
4 From the Push Value To list, select the form that contains the fields to which
you want to push data.
Each Push Fields action can only push data from the current form to one
other form. To push data from the current form to more than one form, you
must create a separate Push Fields action for each form.
98 Chapter 4—Specifying workflow actions
Workflow Objects
5 Enter a qualification in the Push Field If field to specify the request where you
are going to push the data.
You can type the qualification, or you can build it by using the qualification
bar and list, as described in Chapter 3, “Building qualifications.”
WARNING: Typically, you should optimize the Push Field If qualification for
best system performance. In most circumstances, the Push Field If
statement will run a query to retrieve the list of requests in which you will
push data values.
There is one major exception to this rule. When you use the Push Fields
action to always create a request—by entering no qualification in the Push
Field If field, selecting Create a New Request from the If No Requests
Match list, then selecting Take No Action from the If Any Requests Match
list—the AR System server will not scan the entire database and will force
a submission.
The following options are available from the Push Field If list:
Current Form
References fields in the current form. These fields are
delimited with dollar signs ($).
If you want to use a field other than that which appears
on the menu, enter the appropriate '$<field_ID>$'.
<form_name>
References fields in the form to which you are pushing
data (Push Value To). These fields are delimited with
single quotation marks.
If you want to use a field other than that which appears
on the menu, enter the appropriate '<field_ID>'.
Keywords
Lists keywords you can use to build the qualification.
6 From the If No Requests Match list, select a handling option to control how
the system responds when no matches are found in the selected form.
Display ‘No Match’ Error Returns an error message and stops processing.
Take No Action
Skips this action and proceeds to the next action.
Create a New Request
Uses the data you want to push into the database to
create a new request.
The Push Fields active link, filter, or escalation action 99
BMC Remedy Action Request System 7.0
7 From the If Any Requests Match, select a handling option to control how
BMC Remedy User responds when multiple matches are found in the
selected form.
Display ‘Any Match’ Error Returns an error message and stops processing.
Modify First Matching
Request
Pushes data to the first request that meets the
qualification.
Modify All Matching
Requests
Pushes data to every request that meets the
qualification.
Take No Action
Skips this action and proceeds to the next action.
8 To define how field values are mapped from the source form to the target
form, select one of the following options:
Custom
Enables you to define, on a field-by-field basis, which fields
from the source form are mapped to the target form. (This is
the default.)
Matching Ids
All matching field IDs (except for table columns, page holders,
and system-generated core fields—Status History, Modified
Date, Last Modified By, Create Date, and Entry ID) will be
automatically pushed from the source form to the target form.
This option is convenient for quickly creating mappings for two
forms with many matching field IDs.
The rest of the Fields box becomes disabled and you cannot
choose any field mappings.
If you are using a pre-5.0 AR System server, the Matching IDs option is
disabled.
9 From the Name list, select the field to which you want to push data with this
action. (This option is available only if you selected Custom in step 8.)
If you want to use a field source other than that which appears in the Name
field, enter the appropriate '<field ID>'.
10 In the Value field, enter the value you want to push to the other form when
the action executes. (This option is available only if you selected Custom in
step 8.)
100 Chapter 4—Specifying workflow actions
Workflow Objects
You can type the field name or you can use the Value list to insert field values
from the “from” form, keywords, functions, or a combination of these. For a
list of available functions, see “Assigning values using function results” on
page 222. For more information about values, see “The Set Fields active link,
filter, or escalation action” on page 112.
After you enter both a name and a value, the field is automatically added to
the Field Name list.
11 Repeat step 9 and step 10 for as many fields as needed.
12 To delete fields from the Field Name list, select the appropriate fields, and
then press the DELETE key.
13 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Push Fields action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the forms on the
server.
14 For additional Push Fields options, click Advanced.
The Advanced options let you dynamically define which server and form you
will push data to at runtime. For more information, see “Defining advanced
Push Fields action functions” on page 101.
15 Click Add Action (or click Modify Action).
The Push Fields action appears in the Current Actions list.
Defining advanced Push Fields action functions
You can define advanced Push Fields action functions that provide enhanced
functionality beyond pushing data to requests on a specific hard-coded
server and form defined in the workflow action. Based on values that
workflow or users enter into certain fields, you can dynamically select which
server and form you will “push” the data to.
The Push Fields active link, filter, or escalation action 101
BMC Remedy Action Request System 7.0
For example, the Push Source form (as shown in Figure 4-20) contains two
fields (server and form) that can be hidden or display-only. The values
entered into these fields determine at runtime which server and form are
used as sources in the Push Fields action. When you click the button that
triggers the active link, a field value from the Push Source form on the source
server (polycarp) is pushed into the Short Description field on the Push
Target form on the destination server (cordova). Administrators might
prefer to hide this functionality from users altogether and use the Window
Loaded execution condition instead.
In this example, you define the values in a record using the dynamic Push
Fields active link action. If you opened the Push Source form in BMC
Remedy User and entered cordova as the server, Push Target as the form,
and Test Push Data in the Short Description field, clicking Button then
executes the advanced Push Fields action. The server and form have become
dynamically defined in the Push Fields workflow, and the value in the Short
Description field is “pushed” to the Push Target form.
Figure 4-20: Using dynamic workflow to push data to another form
source server
destination server
102 Chapter 4—Specifying workflow actions
Workflow Objects
Note: On the web, Dynamic Push Fields actions cause the browser to perform
extra HTTP fetches and cause the AR System server to perform extra
queries to determine the data types for remote fields. So that the mid tier
can fetch these data types ahead of time and avoid performance
degradation, avoid using field references to store the server or form
names.
To define advanced Push Fields action functions
1 Select Advanced in the Push Fields action.
The window changes in the following ways:
The Server Name (active links only) and Push Value To fields have boxes
that allow you to enter field references or keywords for the server and field
names. Field references are from the reference form (for example, Push
Source) that you chose on the Basic tab and are typically hidden.
The Sample Server Name (active links only) and Sample Form Name
fields you select appear (as shown for an active link in Figure 4-21). You
use these “sample” fields to complete the Custom or Matching IDs field
mapping section of the Push Fields action. The “sample” form must
contain field IDs that exist on any dynamic destination forms that are used
at runtime. But the sample server and form are not actually used at
runtime; the fields you pick are only used to build the workflow.
The Push Fields active link, filter, or escalation action 103
BMC Remedy Action Request System 7.0
Figure 4-21: Advanced functionality of Push Fields active link action
Note: If fields with same IDs on the sample and dynamic forms have different
data types, the general conversion rules apply.
2 In the Server Name (active links only) and Push Value To fields, enter a field
(or choose a field or keyword from the list) that will dynamically select which
server and form to use.
104 Chapter 4—Specifying workflow actions
Workflow Objects
The server and form a user (or workflow) enters into those fields will be used
as the target server and form to populate the form when the Push Fields
action executes.
For active links, use the menu list to enter values into the Server Name and
Push Value To fields.
For filters and escalations, use the menu list to enter a value only into the
Push Value To field. You cannot choose a different server. Filter execution
does not allow the use of the form on a different server.
The server and form you choose must be in their variable format. For
example, if you choose the field labeled server from the Server Name field
list, it appears as $server$, as shown in Figure 4-21.
3 From the Sample Server Name (active links only) and Sample Form Name
lists, select a reference server and form.
The value menu is populated with fields from the reference form. Select field
names with IDs that correspond to field IDs available on any dynamically
selected form at runtime.
The “sample” server and form are used as a temporary reference to create and
save the Push Fields workflow. You can even delete the sample form after
saving the action. What is important is being able to map the custom IDs
between the forms in step 5, in this case between the two Short Description
fields.
4 Enter a qualification in the Push Field If field to specify the request that
contains the values that you want to retrieve.
The fields from the sample form can be used in the qualification. The fields
and field IDs on the sample form and the corresponding dynamic form
should be the same types because conversion rules do not apply in this case.
5 Map the field and value that you are setting with this action.
In this example, the value of whatever is in $Short Description$ from the
source form is “pushed” to the Short Description field on the dynamicallyidentified target form. To share this dynamic workflow among several forms,
make sure that your forms have corresponding (or matching) field IDs. (For
more information, see “Shared workflow” on page 22.)
6 Click Add Action (or click Modify Action).
The Push Fields action appears in the Current Actions list.
The Push Fields active link, filter, or escalation action 105
BMC Remedy Action Request System 7.0
The Run Macro active link action
You can use the Run Macro action to specify a macro to run whenever the
active link is executed in BMC Remedy User. (The Run Macro active link
action is not available for the web client.) The macro can perform any
operation or series of operations. If the macro contains parameters, you can
specify values for those parameters, including a value from a field in the
current request.
For example, you might designate the value entered in the Customer Name
field of the current request for use as the parameter value in a macro that
queries the database for information about a specified customer. Or you
might create a macro that generates a report and attach it to a button.
To use a macro in an active link, you must first create the macro by using
BMC Remedy User. (For information about creating a macro, see BMC
Remedy User Help.) The macro that you specify is copied into the active link.
Changes that you make to this macro after the active link is created will not
affect the operation of the active link. If you want macro changes to apply to
the active link, you must modify the active link and specify the macro again.
Most operations that can be performed from a macro can be performed from
other actions. Use the Run Macro action type only for backwardcompatibility with clients prior to the 5.0 release.
Note: You can use the $VERSION$ keyword to include or exclude older
Windows user tool clients in workflow. For UNIX user tool clients, use the
$OS$ keyword. For more information, see “$VERSION$” on page 208.
Two Run Macro actions cannot be converted:
When you use the query bar inside the macro and:
Field names and field labels on the current form are different.
You use field IDs not on the current form as a parameter inside the
query.
Any action involving logging in.
106 Chapter 4—Specifying workflow actions
Workflow Objects
To define the Run Macro active link action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Run Macro.
The fields required to define the Run Macro action appear. Figure 4-22
shows these fields and an example of how a Run Macro active link action
might look after you complete the remaining steps in this procedure.
Figure 4-22: Run Macro active link action
The menu button is used to
select fields or keywords.
This button appears when
you click on a macro
parameter name.
3 From the Macro Name list, select the appropriate macro.
If the macro contains parameters, a list of parameters appears.
4 If parameters are listed, optionally enter any of the following as parameter
values:
A static value
A keyword
A reference to any field in the current form
The Run Macro active link action 107
BMC Remedy Action Request System 7.0
Field references and keywords must be enclosed within dollar signs. For
example, if you want the contents of the Customer Name field to be used
for a particular parameter in the macro, enter $Customer Name$.
You can enter a field reference or keyword by clicking the parameter
name. A menu button appears so that you can select fields from the
current form (as in the previous figure) or keywords. If you specify a field
as a parameter, the macro uses the value that it finds in the field in the
window from which the active link was executed.
The macros will not prompt for values when executed from active links. You
must specify values here for the parameters.
If you want to prompt, use a dialog box to prompt for values (as described in
the Form and Application Objects guide). The values will assign the fields
loaded from the dialog box to the macro parameters.
5 To save the macro to another area on the network, click the Save To Disk
button.
6 Click Add Action (or click Modify Action).
The Run Macro action appears in the Current Actions list.
The Run Process active link, filter, or escalation action
Use the Run Process action to execute a command to run an independent
process on a client or an AR System server. The system will execute the
command specified in the Command Line field. For example, you can specify
a program that sends a fax or that makes a log entry in a specific format. The
command line can include parameters.
The Run Process action only executes an independent process; it does not
return a value. To insert the result of a process into a field, set the field by
using the value resulting from a process (see “Assigning values from process
results” on page 234).
Some, but not all, Run Process commands will run in a browser.
For more information, see Appendix C, “Special Run Process and
$PROCESS$ commands.”
108 Chapter 4—Specifying workflow actions
Workflow Objects
WARNING: If the process executed with the Run Process command runs on
the client, it will use the permissions of the user who started BMC Remedy
User or the web client. If the process executed with the Run Process
command runs on the server, it will use the permissions of the user who
started the AR System server. Running a process using a filter can have
security implications for your system.
For active links that run processes on the server, AR System provides a
security feature that allows you to define the only directory from which
active link processes can execute on the server. For more information, see
permission and configuration information in the Configuring guide.
To avoid degrading performance on web clients, always specify the action in
the run process command, instead of indirectly through a field. For example,
a command like the following is acceptable:
PERFORM-ACTION-ADD-ATTACHMENT 536870912
But the following command would cause performance on the client to
degrade:
$536870914$ 536870912
To define the Run Process active link, filter, or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Run Process.
The Command Line field appears. The following figure shows this field and
an example of how the Run Process active link action might look after you
complete the remaining steps in this procedure.
The Run Process active link, filter, or escalation action 109
BMC Remedy Action Request System 7.0
Figure 4-23: Run Process active link action
Field contents can be used
as parameters.
Enclose field names with $
signs or use the list.
3 In the Command Line field, enter the command that you want to execute.
You can type the command, or you can build the command by using the
Command Line list to insert field values from the current request or
keywords (see “Keywords” on page 203). The field or keyword will be
expanded when the process is run. Both fields and keywords must be
enclosed in dollar signs. If an expanded value contains spaces, you must
manually insert double quotation marks around the parameter so that the
operating system interprets it as a single value.
You can enter a maximum of 255 characters for your command definition.
When run on the client, the fully expanded command line cannot exceed
4096 bytes.
Click the text edit button to open a text dialog box for easier data entry.
110 Chapter 4—Specifying workflow actions
Workflow Objects
In active links, the syntax identifies where the process that you want to run is
located. To run a process:
On the same machine as the client, enter:
<process_to_run>
On the current AR System server, enter:
@@:<process_to_run>
On any specific AR System server, enter:
@Server_B:<process_to_run>
For active links, when you run a process on the client, be aware that the
process you are specifying might not be available on all hardware platforms
and operating systems that your clients might be using. If your users run the
client tools on more than one type of platform or operating system, you can
build a qualification for the active link by using the $HARDWARE$ and $OS$
keywords to verify that the client is running on an appropriate platform or
operating system at the time the active link executes. See Chapter 3, “Building
qualifications,” for more information.
4 Click Add Action (or click Modify Action).
The Run Process action appears in the Current Actions list.
Command line syntax guidelines
The following guidelines for command line syntax are recommended:
Adjust your command syntax appropriately for the platform on which
your server is running, and include the explicit path to the command; for
example, /home/jim/bin/<command>. In the Windows environment,
specify the drive; for example, d:\home\jim\bin\<command.bat>.
In the UNIX environment, the process runs under a Bourne shell.
On a Windows server, you can run only a process that runs in a console
(such as a .bat script or an executable like runmacro.exe).
Use double quotation marks around substituted fields when the values
might contain spaces or other special characters; for example,
/bin/cmd "$<field>$".
The Run Process active link, filter, or escalation action 111
BMC Remedy Action Request System 7.0
Substituted field values that contain hard returns or other special
characters can have unexpected results.
The AR System server does not interpret environmental variables for the
Run Process action. To use environmental variables, you must include the
path to the command-line executable in the command-line statement, as
in the following Windows example (cmd.exe), "C:\Program
Files\I386\cmd.exe %windir%\system32\mplay32.exe
%windir%\Media\chimes.wav". For UNIX, you would include a reference
to /bin/sh in the path.
The Set Fields active link, filter, or escalation action
Use the Set Fields action to move data to the current request from any of the
following data sources:
Field in the same form
Field in another form on the same server or a different server
SQL command
Filter API plug-in service
Function
Result of an independent system process
DDE operation (active link only)
OLE operation
Result of a mathematical calculation
Web service
To move data from the current request to another request, see “The Push
Fields active link, filter, or escalation action” on page 97.
For active links, Set Fields actions that execute on After Submit or After
Modify update the specified fields on the screen. However, they do not write
the values to the database, nor do they update the change flag (Save button).
You can use the Set Fields action to load specific values into selected fields
each time certain conditions are met. This enables you to automate field
updates for a request. For example, you can define a filter that will
automatically set the State field to Assigned every time the Assigned To field
is set to a support staff name.
112 Chapter 4—Specifying workflow actions
Workflow Objects
You can use the Set Fields action to load values into hidden fields, into fields
not in the active view, or into fields in no views at all. However, you cannot
use the Sets Fields action for column fields and page holders.
When you use a set fields action with attachments, note that the order of the
attachments might change.
Values loaded into diary fields with the Set Fields action are handled as
follows:
Filters and escalations add the new text to the old text.
Active links replace the new text.
This difference of functionality is an important consideration whether you
might use an active link in one situation, but a filter in another.
Also, if you set multiple fields in one action, the order of the set fields might
execute differently on BMC Remedy User and web clients and might give you
different results. If you have dependent fields, you should always break up the
set fields into multiple Set Field actions so that field dependencies are
executed correctly. This will guarantee that BMC Remedy User and web
clients work the same.
The fields required to define the Set Fields active link, filter, or escalation
appear in the following figure. The figure also shows an example of how a Set
Fields active link action might look after you create it.
The Set Fields active link, filter, or escalation action 113
BMC Remedy Action Request System 7.0
Figure 4-24: Set Fields active link action
To define a Set Fields active link, filter, or escalation action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Set Fields.
114 Chapter 4—Specifying workflow actions
Workflow Objects
3 From the Server Name list, select the server source that contains the value
that you want to load. The options are:
CURRENT SCREEN
(active links)
The field references in the Value column will be to the
current request. This means the system will copy fields
to each other on the current screen.
CURRENT
TRANSACTION (filters
and escalations)
The field references in the Value column will be to the
current request. This means the system will copy fields
to each other within the current transaction and not
from the database.
<server_name>
Sets the field in the current request with a value from
the database, as follows:
For active links, from another request in this form, or
from another form on this server or another server.
For filters and escalations, from another request in
this form, or from another form on this server.
4 From the Read Value for Field From list, select the form or source that
contains the value that you want to load:
CURRENT SCREEN
(active links)
The field references in the Value column will be to the
current request.
If you enter a server name and form different than the
CURRENT SCREEN, but you do not reference a field
from another form, there is no need to retrieve a value
from the database, and the server name and form will
revert to CURRENT SCREEN.
CURRENT
TRANSACTION (filters
and escalations)
The field references in the Value column will be set
with a value that is not from the database. This could
be a value from the current request, a keyword, a filter
API plug-in service, an SQL command, or a static
value.
If you enter a form different than the CURRENT
TRANSACTION but you set the field by using a static
value or a keyword, or if you do not set the field from
another form, there is no need to retrieve a value from
the database, and the form reverts to CURRENT
TRANSACTION.
SQL (active links, filters,
and escalations)
The SQL Command fields appear, and you can enter a
command for the system to perform.
FILTER API (filters and
escalations)
The Filter API Input fields appear, and you can enter
information for the filter API you want to use.
The Set Fields active link, filter, or escalation action 115
BMC Remedy Action Request System 7.0
WEB SERVICE (filters and The Web Service fields appear, and you can load a
escalations)
WSDL.
<form_name>
The Set Field If fields appear, and you can enter a
qualification to specify the request that contains the
values you want to retrieve.
5 Perform one of the following tasks to complete the Set Fields action:
If you selected CURRENT SCREEN or CURRENT TRANSACTION,
complete steps 8 and 9.
If you selected SQL in the Read Value for Field From list, see “Assigning
values by submitting SQL commands” on page 214.
If you selected FILTER API in the Read Value for Field From list, see
“Assigning values by issuing requests to a Filter API Plug-In service” on
page 219.
If you selected WEB SERVICE in the Read Value for Field From list, see
the Integrating with Plug-ins and Third-Party Products guide for complete
instructions.
If you selected <form_name> in the Read Value for Field From list,
complete steps 6–13.
6 Enter a qualification in the Set Field If field to specify the request that
contains the values that you want to retrieve.
You can type the qualification or you can build it by using the qualification
bar and list, as described in Chapter 3, “Building qualifications.” The
following options are available from the Set Field If menu button:
Current Form
References fields in the current screen (active links) or
current form (filters or escalations). These fields are
delimited with dollar signs ($).
If you want to use a field other than that which appears on
the menu, enter the appropriate '$<field_ID>$'.
<form_name>
References fields in the form from which you are drawing
data (Read Value for Field From). These fields are delimited
with single quotation marks.
If you want to use a field other than that which appears on
the menu, enter the appropriate '<field_ID>'.
Keywords
Lists keywords you can use to build the qualification.
116 Chapter 4—Specifying workflow actions
Workflow Objects
WARNING: You should optimize the Set Field If qualification for best system
performance. The Set Field If statement always runs a query to retrieve a
list of the requests to get data values from.
7 From the If No Requests Match list, select a handling option to control how
the system responds when no matches are found in the selected form.
Display
‘No Match’ Error
Returns an error message and stops processing.
Set Fields to
$NULL$
Assigns a NULL value to all of the fields that you are setting
(except for fields with static values and keywords).
8 From the If Multiple Requests Match list, select a handling option to control
how the system responds when multiple matches are found in the selected
form.
Display ‘Multiple
Match’ Error
Returns an error message and stops processing.
Use First Matching
Request
Inserts the value of the first request that meets the
qualification.
Set Fields to
$NULL$
Assigns a NULL value to all of the fields that you are setting
(except for fields with static values and keywords).
Display a List (active Displays a selection list so the user can select the appropriate
links only)
request. The selection list uses the form’s result list
specification.
Use First Matching
Request Based On
Locale
Returns localized information to determine the match.
The contents of the Locale field (special field ID 160) are used
along with the current user's locale to select the best match.
If there are several matches with the same locale, then the first
match is returned.
If there is no localized server or no Locale field in the form,
this option becomes the same as Use First Matching Request
option. For more information about using the Locale field
with localizing search menus, see the Form and Application
Objects guide.
The Set Fields active link, filter, or escalation action 117
BMC Remedy Action Request System 7.0
9 Define how field values are mapped from the source form to the target form
by selecting one of the following options:
Custom
Lets you define, on a field-by-field basis, which fields from the
source form are mapped to the target form. (This is the default.)
This option is activated only when you select a source form that
is not CURRENT SCREEN. (Setting Matching Ids fields to the
current form from the current form does not make sense and is
not a valid operation.)
Matching Ids
All matching field IDs (except for table columns, page holders,
and core fields such as Modified Date and Entry ID) will be
automatically set in the target form from the source form. This
option is convenient for quickly creating mappings for two
forms with many matching field IDs.
The rest of the Fields box becomes disabled, and you cannot
choose any field mappings.
If you are using a pre-5.0 AR System server, the Matching Ids
option will be disabled.
10 If you selected Custom in the previous step, perform the following steps:
a From the Name list, select the field that you are setting with this action.
If you want to use a field source other than that which appears in the Name
field, enter the appropriate '<field ID>'.
b In the Value field, enter the value that you want to load when the action
executes.
You can type the field name or you can use the Value list to insert field
values from the “from” form, keywords, functions, $PROCESS$, or $DDE$
(for active links only). You can set the field values to any of the following
options:
A value from another field in the same form or from another form.
A static value. Enclose text values that include special characters (such
as parentheses, single quotation marks, or arithmetic operators) in
double quotation marks.
A keyword value (see “Keywords” on page 203).
The value resulting from issuing an SQL command to the database (see
“Assigning values by submitting SQL commands” on page 214).
118 Chapter 4—Specifying workflow actions
Workflow Objects
The value returned from issuing a filter API plug-in service (see
“Assigning values by issuing requests to a Filter API Plug-In service” on
page 219).
The value resulting from a function (see “Assigning values using
function results” on page 222).
The value resulting from a specified process (see “Assigning values from
process results” on page 234).
The value resulting from an arithmetic operation (see “Assigning values
by using arithmetic operators” on page 237).
The value resulting from a DDE request operation on a Windows client
(see the Integrating with Plug-ins and Third-Party Products guide).
A combination of the previous items in this list. For example, you can
combine a static text entry with a keyword, "Entry entered by " +
$USER$.
Note: Because filters and escalations execute with administrator permissions,
field values set through a filter or escalation are updated even if the user
does not have permission to change the field. However, active links
execute with the permissions of the user, so field values set through an
active link are updated in the database only if the user has permission to
change the field.
After you select a name and a value, the field is automatically added to the
Field Name list.
a Repeat these steps for as many fields as needed.
b To delete fields from the Field Name list, select the appropriate fields, and
then press the Delete key.
11 (For deployable applications only) Select the Restricted List check box
(default option) to restrict the Set Fields action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the forms on the
server.
The Set Fields active link, filter, or escalation action 119
BMC Remedy Action Request System 7.0
12 For additional Set Fields options, click Advanced.
The Advanced options let you dynamically specify which server and form will
be used to read the data from at runtime. For more information, see
“Defining advanced Set Fields action functions” on page 120.
13 Click Add Action (or click Modify Action).
The Set Fields action appears in the Current Actions list.
Defining advanced Set Fields action functions
You can define advanced Set Fields action functions that provide enhanced
functionality beyond setting data in requests from a hard-coded server and
form defined in the workflow action. Based on values that workflow or users
enter into certain fields, you can dynamically select which server and form
you are reading the data from.
For example, the Target form (as shown in Figure 4-25) contains two fields
(server and form) that can be hidden or display-only. The values you enter
into these fields (they could also be set by workflow) determine at runtime
which source server and form are used as sources in the Set Fields action.
When you click the button that triggers the active link, a field value from the
Source form on the source server (cordova) is set into the Short Description
field on the Target form on the destination server (polycarp). Administrators
might prefer to hide this functionality from users altogether and use the
Window Loaded execution condition instead.
Figure 4-25: Using dynamic workflow to set fields
120 Chapter 4—Specifying workflow actions
Workflow Objects
In this example, a simple record was created in the Source form on the server
cordova. The Short Description field on Source contains the value, Test
Data. If you opened form Target in BMC Remedy User and entered cordova
as the server and Source as the form, clicking Button would execute the
advanced Set Fields action. The server and form have become dynamically
defined in the Set Fields workflow and the Short Description field is “set”
with the Test Data value.
To define advanced Set Fields action functions
1 Select Advanced in the Set Fields action.
The window changes in the following ways:
The Server Name (active links only) and Read Value for Field From fields
have boxes that allow you to enter field references or keywords for the
server and form names. These fields come from the base form (for
example, Target) that you chose on the Basic tab and are typically hidden.
The Sample Server Name (active links only) and Sample Form Name
fields appear (as shown for an active link in Figure 4-26). Default values
listed are the current server and form. You use these “sample” fields to
complete the Custom or Matching IDs field mapping section of the Set
Fields action. The “sample” form must contain field IDs that exist on any
dynamic source forms that are used at runtime. But the sample server and
form are not actually used at runtime; the fields you pick are only used to
build the workflow.
The Set Fields active link, filter, or escalation action 121
BMC Remedy Action Request System 7.0
Figure 4-26: Advanced functionality of Set Fields active link action
Note: If fields with same IDs on the sample and dynamic forms have different
data types, the general conversion rules apply.
122 Chapter 4—Specifying workflow actions
Workflow Objects
2 In the Server Name (active links only) and Read Value for Field From fields,
enter a field or keyword that will dynamically specify which server and form
are used.
The server and form that a user (or workflow) enters into those fields will be
used as the source server and form from which to retrieve values when the Set
Fields action executes:
For active links, use the menu list to enter values into the Server Name and
Read Value for Field From fields.
For filters and escalations, use the menu list to enter a value into the Read
Value for Field From field. You cannot choose a different server. Filter
execution does not allow the use of a form on a different server.
The server and form you choose must be in their variable format. For
example, if you choose the field labeled form from the Read Value for Field
From field list, it appears as $form$, as shown in Figure 4-26.
3 From the Sample Server Name (active links only) and Sample Form Name
lists, select a reference server and form.
The value menu is populated with fields from the “sample” form. Select field
names that correspond to field IDs available on any dynamically selected
form at runtime.
The “sample” server and form are used as a temporary reference to create and
save the Set Fields workflow. You can even delete the sample form after
saving the action.
4 Enter a qualification in the Set Field If field to specify the request that
contains the values that you want to retrieve.
The fields from the sample form can be used in the qualification. The fields
and field IDs on the sample form and the corresponding dynamic form
should be the same types because conversion rules do not apply in this case.
5 Map the field and value that you are setting with this action.
In this example, the Short Description field on the target form is being “set”
with the value of whatever is in $Short Description$ from the dynamicallyidentified source form. To share this dynamic workflow among several
forms, make sure that your forms have corresponding (or matching) field
IDs. (For more information, see “Shared workflow” on page 22.)
6 Click Add Action (or click Modify Action).
The Set Fields active link, filter, or escalation action 123
BMC Remedy Action Request System 7.0
The Wait active link action
Use the Wait action to suspend a guide in BMC Remedy User so that the user
has an opportunity to interact with a field. For more information about
guides, see Chapter 5, “Defining guides and guide actions.”
Specifying escalation time criteria
Use the Time Criteria tab in the Escalation window to define an escalation to
execute at a specific time or time interval.
Note: Escalations that check the server too frequently can cause performance
problems. With the 5.x and later releases of AR System, all servers include
a dedicated escalation queue, which is automatically created by the system
for you. See the Optimizing and Troubleshooting guide for more
information.
To define escalation time criteria
1 Click the Time Criteria tab.
2 Under Execution, select an execution option to control when the server
checks the escalation conditions.
Interval
Checks escalation at a regular interval (for example, every 30
minutes, every six hours, every seven days, or any combination of
days, hours, and minutes). The interval begins when you create,
modify, or enable the escalation, and the interval begins when the
server is restarted.
Time
Checks escalation at a specified time (for example, every day at 4:00
p.m. or 1600 hours). This option enables you to check escalations at
irregular intervals, for example, the 15th and 31st of every month or
weekdays at 10:00 a.m. and 2:00 p.m.
To define an execution interval
1 From the Execution section, select Interval.
2 In the Days, Hours, and Minutes fields, enter a time interval.
124 Chapter 4—Specifying workflow actions
Workflow Objects
The server checks the escalation immediately, and then every interval of time
thereafter. For example, if you set the interval to 1 hour and 30 minutes, the
server will check the escalation as soon as you save it, then every 90 minutes
thereafter.
When the server is restarted, intervals start at that time.
To define an execution time
1 From the Execution section, select Time.
You can select any combination from the Day of Month, Weekdays, Hour of
Day, and Minute regions.
Figure 4-27: Time criteria in escalation window
For a valid time escalation setting, you must select from the following
categories:
Day of Month, Weekdays, or both
Hour of Day
Specifying escalation time criteria 125
BMC Remedy Action Request System 7.0
For example, if you select 15 and 31 from the Day of Month calendar and
Fridays from the Weekdays list, the server checks the escalations on the 15th
and 31st and all Fridays during the month. If a Friday occurs on a 15th or
31st, the server checks the escalation only once.
To run an escalation every weekday, simply select all the days (except
Saturday and Sunday), and do not select a day in the Day of Month region.
2 In the Day of Month region, select the appropriate days of the month.
All
Selects every day of the month.
None
Clears every day of the month.
Note: Selecting 31 from the Day of Month calendar creates an escalation on
the last day of the month for all months.
3 In the Weekdays region, select the appropriate days of the week.
4 In the Hour of Day region, select the appropriate hours of the day.
5 To specify minutes past the hour, select the appropriate number of minutes
from the Minute list. (The default value is zero.)
It is best not to have multiple escalations set to run at the same time, so the
server load is balanced. For example, you can order escalations so that the
server checks one escalation on the hour, another at 15 minutes past the
hour, another at 30 minutes past the hour, and so on.
Note: There might be irregularities the first time escalations execute after
Daylight Saving Time (DST) transitions. For example, an escalation is
scheduled to run at 12:00 noon every Monday. On the first Monday after
clocks are set ahead, the escalation runs at 1:00 p.m. instead of at noon. On
the first Monday after the clocks are set back, it runs at 11:00 a.m. and
again at noon.
126 Chapter 4—Specifying workflow actions
Chapter
5
Defining guides and guide
actions
This chapter describes how to use BMC Remedy Administrator to create and
modify active link guides and filter guides. The following topics are provided:
Process for creating guides (page 128)
Defining guides (page 130)
Shared guides (page 136)
Guide actions (page 138)
Active link guides (page 148)
Filter guides (page 161)
Defining guides and guide actions 127
BMC Remedy Action Request System 7.0
Process for creating guides
A guide is a workflow program consisting of a series of active links or filters
that can be used for a variety of tasks. When creating guides, it is helpful to
plan them out first. Use the following steps before you begin creating active
link guide objects.
Step 1 Plan the guide.
What will the guide be used for? To lead users through a form? To invoke
a dialog box? To create a computational subroutine? To specify an entry
point guide in the Application List field used on a Home Page form?
What class of user will it guide? Advanced users? Or will you have to guide
novice users step-by-step through a form?
What will the guide form look like? Will you have to create a simple form
for novice users?
Will the guide be shared among multiple forms?
Will your guide function as an access point for applications?
Step 2 Design the guide.
How many steps or dialog boxes will the guide require?
If you are using dialog boxes, plan the layout of forms, fields, and buttons.
Will you require data validation?
What will your prompts say if it is a navigational or training guide?
Step 3 Create the active links or filters that you want to use within the guide. For
more information, see “Guide actions” on page 138.
Use only one active link or filter for each step.
Although you can reuse active links or filters in your guide that were
designed for other applications, some administrators find it is easier to
create new ones, particularly active links, that do not have any Execute On
conditions. Other administrators, to avoid maintenance of yet more active
links and filters, prefer to re-use them.
Keep track of any Go To Guide Label targets used.
128 Chapter 5—Defining guides and guide actions
Workflow Objects
Step 4 Create the guide.
a Set the appropriate specifications for the guide as described in “Defining
guide basics” on page 131.
b Specify the appropriate active links or filters for the guide as described in
“Defining the active links or filters in a guide” on page 133.
c If you are using the Go To Guide Label active link action, add the labels
needed for Go To targets.
d Specify the appropriate guide permissions.
e Specify the appropriate guide change history.
f Create or modify the help text for a guide.
For more information about permissions, building and using change history,
and creating help text, see the Getting Started guide.
Step 5 Debug your guide before sending it to your users.
Use active link logging to generate a list of active links that are executed
and the order in which they are executed.
Use filter logging to generate a list of filters that are executed and the order
in which they are executed.
Provide visual cues as the guide executes, so users will know what actions
to expect.
Make sure the entry point guide works on the Application List field on
your Home Page form.
Create Message active link actions as temporary placeholders to
understand how your guide works.
Step 6 (BMC Remedy User only) To send the completed guide to users through
email, choose File > Send > Form > Mail Recipient.
Your MAPI-compliant email tool is launched with the guide as an
attachment so that you can send the guide to the appropriate users. When
users receive the guide attachment, they can drag the icon to their desktops
and use it as a shortcut to start the guide in BMC Remedy User.
Process for creating guides 129
BMC Remedy Action Request System 7.0
Defining guides
This section describes how to set guide specifications using the tabs of the
Guide window, shown in Figure 5-1.
Use the Guide window to create and modify guides. In this section, Guide
window refers to a Create Guide or Modify Guide window.
Figure 5-1: Guide window
Use the following tabs in the Guide window to define parameters:
Basic
Defines the basic properties of the guide and determines
how you will reference the guide in other parts of BMC
Remedy Administrator.
Active Links or
Filters
Defines the active links or filters that make up the guide.
Permissions
Defines which access control groups can execute the guide.
Subadministrator
Permissions
Defines which subadministrator groups can modify the
guide.
130 Chapter 5—Defining guides and guide actions
Workflow Objects
Change History
Records the owner of a guide, the user who last modified it,
and the date of the modification. You can also enter a
description of your changes.
Help Text
Supplies help text for the guide. Typically, this help text is a
description of the guide, what it does, and how it is used.
Defining guide basics
To define guide basics
1 Open the guide with which you want to work.
2 In the Name field, enter the name (or update the existing name if necessary)
that you want to appear in the BMC Remedy Administrator server window.
Guide names must be unique on each AR System server. There is no enforced
convention for specifying guide names, but it is helpful to make the name
descriptive and indicative of the guide’s function. Guide names can be up to
80 characters, including spaces. Names can include double-byte characters,
but avoid using numbers at the beginning of the name.
3 In the Label field, enter a name.
This label appears in two different places in AR System:
Open dialog box in BMC Remedy User.
Entry point guide on the Application List field on your Home Page form.
There is no enforced convention for specifying guide labels, but it is helpful
to make the name descriptive and indicative of the guide’s function. Labels
can be as many as 255 bytes.
If you do not supply a label, the guide name is used as the guide label.
4 In the Description field, enter a description of the guide suitable for end
users. (optional)
This description is displayed in the box below the task list in the Open dialog
box when this guide is selected. The description that you enter here also
appears in the Active Link window when you use this guide in a Call Guide
active link action. You can enter a maximum of 2000 bytes.
5 From the Form Name list, select the form (or forms) to which the guide will
apply.
Defining guides 131
BMC Remedy Action Request System 7.0
Because a guide can be shared by one or more forms, it also can contain
multiple active links from those forms. All active links associated with the
selected forms appear in the Active Links in Form list in the Active Links tab
of this Guide window. (See “The Exit Guide active link or filter action” on
page 144 for more information.) As a result, you can access those active links
only from the forms listed in the Form Name field. Active links that are not
associated with a form that the guide is running will not execute.
If you select multiple forms, the guide will be attached to all of them. The first
form you select becomes the reference form and appears checked at the top
of the list in bold text. The reference form is simply the first form in the list
to which the guide is attached. For more information, see “Shared guides” on
page 136.
Checked forms appear alphabetically at the top of the Form Name list. If the
check box is:
Selected and bold—It is the reference form.
Selected but not bold—The workflow will be attached to this form.
Cleared—The workflow will not be attached to this form.
When selecting forms from the list you can:
Use the keyboard arrow key or type a letter to scroll through the list.
Use the spacebar to select or clear a form.
Click the right mouse button on any of the selected forms to use the
context menu to change to a different reference form.
6 (For active links guides only) To create an entry point guide to appear on the
application list field, perform the following steps:
a Select the Entry Point check box. This activates the guide so that it will
appear as an entry point in the Application List field on your Home Page
form.
b In the Application List Display Order field, specify what order that you
want your guide to appear in the application list of entry points.
c From the Starting Active Link menu list, select the starting active link for
the guide. This active link can use different actions, but it should at least
use the Open Window action.
For more information, see the Form and Application Objects guide.
132 Chapter 5—Defining guides and guide actions
Workflow Objects
Defining the active links or filters in a guide
The active links or filters included within a guide determine the guide’s
functionality.
To define active links or filters in a guide
1 Open the guide with which you want to work.
2 Click the Active Links or Filters tab (Figure 5-2 on page 133).
The Active Links (or Filters) in Form list shows all active links (or filters)
associated with the forms that are selected on the Basic tab. The Active Links
(or Filters) in Guide list shows the active links or filters that are part of the
guide.
Figure 5-2: Guide window—Active Links tab
Defining guides 133
BMC Remedy Action Request System 7.0
3 In the Active Links (or Filters) in Form list, select the active links or filters you
want to include in the guide, and click Add.
The selected actions appear in the Active Links (or Filters) in Guide list, and
they execute in the order in which they appear in the list. You can change the
order by using the up and down Move buttons.
To remove active links or filters from the guide, select the action in the Active
Links (or Filters) in Guide list, and then click Remove.
To use the same active link or filter more than once in a guide, select it and
click Add.
4 To add a label before an active link or filter so that you can reference it in a
Go To Guide Label action:
a Select the active link or filter from the Active Links (or Filters) in Guide
list.
b Click Add Label.
c Right-click the label, and choose Edit Label.
d Type the new label.
You can move and remove labels as described in step 3.
For more information about the Go To Guide label, see “The Go To Guide
Label active link or filter action” on page 145.
Setting permissions
Use the Permissions tab to set permissions for the guide. For active link
guides, permissions define those access control groups that are allowed to
view and execute the active link guide.
WARNING: Remember that active links have permissions, which are enforced
when running the guide. Any active link in a guide to which a user does
not have access will be skipped.
You do not assign permissions in a filter guide. Filters execute on the
AR System server and run with administrator permissions. This means that
filters can access any field in the AR System database, even if the field is not
available to the user (no view or change access).
134 Chapter 5—Defining guides and guide actions
Workflow Objects
Building and using guide change history
AR System automatically records the owner of a guide, the administrator
who last modified the guide, and the date of the modification. To display or
add to this information, click the Change History tab in the Guide window.
For more information about building and using change history, see the
Getting Started guide.
Creating help text for guides
To create or modify the help text for a guide, click the Help Text tab in the
Guide window. Typically, the help text that you enter is a description of the
guide, what it does, and how it is used. Guide help text can be edited only by
administrators and subadministrators with access to the guide to which the
help text applies. Administrators and subadministrators can view the help
text you enter here in the Active Link window when this guide is used in a
Call Guide active link action. For more information about creating help text,
see the Getting Started guide.
Logging guide activity
You can create a log file of active link activity that will include all of the active
links in a guide. This option logs information about active link activity for
each operation, including which active links executed and whether active link
execution was successful. Active link logging is enabled in BMC Remedy
User. For information about enabled active link logging, see BMC Remedy
User help.
Modifying guides
When modifying a guide, you do not need to send the modified guide to your
users. The shortcut that you sent to your users is a pointer to the guide
definition that resides on the AR System server.
Deleting guides
After you have deleted a guide, tell your users to delete the guide shortcuts
from their desktops. If users try to start a guide after it has been deleted from
the server, they will receive an error message.
Defining guides 135
BMC Remedy Action Request System 7.0
Shared guides
Guides can be shared by multiple forms. The way you define shared guides is
similar to the way you define a guide for an individual form, except that you
attach the guide to multiple forms. If you do not want the guide to be shared,
select only one form. Also, share any active links in the shared guide that you
want to execute on multiple forms. If a guide contains active links that do not
belong to or are not shared with the current form, those active links will be
skipped when the guide is executed.
Note: Any changes you make to shared active links affect all guides and forms
that use them.
For more information about creating shared workflow, see “Shared
workflow” on page 22.
The sequence of active links in the guide takes precedence over any execution
condition previously defined for the active links. You can redirect the active
links by using the Go To Guide Label action. If you are creating active links
that will be used only in a guide, then do not include an Execute On condition
in them, as both the condition and its execution order are ignored when the
guide’s active links are executed.
Guides use the following procedures when determining which form to run
on:
Step 1 Search for the current form.
Step 2 If the current form belongs to the guide, run the guide against that form.
Step 3 If the current form does not belong to the guide, open a new window with a
reference form and run the guide.
136 Chapter 5—Defining guides and guide actions
Workflow Objects
Shared guide examples
The following examples illustrate shared guide behavior. Assume you have
created guide X and shared it with forms A, B, and C.
To create a shared guide—example 1
1 Create a Call Guide active link action for forms A, B, and C.
2 Open form A and execute the Call Guide action.
Guide X will be executed upon form A.
To create a shared guide—example 2
1 Create a Call Guide active link action for forms A, B, and C.
2 Open form C and execute the Call Guide action.
Guide X will be executed upon form C.
To create a shared guide—example 3
1 Designate Form B as the reference form.
2 Create a Call Guide active link action for forms A, B, C, and D.
3 Open form D and execute the Call Guide action.
A new window will open with the reference form B.
Guide X will be executed upon form B in a new window.
To create a shared guide—example 4
1 Form A is designated as the reference form.
2 Open guide X from the Open dialog box.
Guide X will be executed upon form A, the reference form.
Shared guides 137
BMC Remedy Action Request System 7.0
Guide actions
This section discusses the actions used to create a guide:
Call Guide
Exit Guide
Go To Guide Label
Wait
The Call Guide active link or filter action
Use the Call Guide action to start a guide. Active links and filters that execute
in the context of guides are not triggered by the same Execute On conditions
that trigger them during normal workflow. The Call Guide and the Go To
Guide Label actions (see “The Go To Guide Label active link or filter action”
on page 145) trigger the first or the specified active link or filter in the guide
and every active link or filter that follows.
The Call Guide action can be used for “looping” through the rows of a table
field (also known as “table walk”). For more information, see “To create a
guide that walks you through a table field” on page 153.
Note: AR System does not allow a Call Guide action that calls the guide itself.
However, AR System allows recursive call guides; for example, CallGuide1
calls CallGuide2, and then CallGuide2 calls CallGuide1. You can create
this scenario, but be aware that an infinite loop can occur. If this happens,
BMC Remedy User will hang, and the mid tier will generate a JavaScript
error.
To define the call guide active link or filter action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Call Guide.
The fields required to define the Call Guide action appear.
138 Chapter 5—Defining guides and guide actions
Workflow Objects
Figure 5-3: Call Guide active link action
Select Call Guide.
Click twice on this label and
type a server name to add
that server to the list.
3 In the Call Guide field, double-click the server that contains the guide that
you want to start.
A list of call guides on that server appears.
Tip: To add a new server to the list, click the Add New Server to List label
twice (not a double-click). Then, type the new server name and press
Enter.
4 Select the guide that you want to call when the active link conditions are met.
The form to which the selected guide is attached appears in the Form Name
field, and any text that you entered in the Description field in the Basic tab of
the Guide window appears in the box below it.
Guide actions 139
BMC Remedy Action Request System 7.0
5 If you are using the Call Guide active link or filter action to “walk” the rows
of a table, click the Table Loop check box, and choose from the list of
available table fields.
6 For active links only, click the Table Loop Selected Rows Only check box.
Using this option significantly improves the performance of table loop
guides because the looping action is performed only on the selected rows, not
through every row in the table field. (For additional performance tips, see
“Enhancing performance of table loops” on page 140.)
7 (For deployable applications only) Select the Restricted List checkbox
(default option) to restrict the Call Guide action only to the forms in the
application.
Clearing the Restricted List checkbox lets you access all the guides on the
server.
8 (Optional) Click the Advanced check box to supply “dynamic” server (active
links only) and guide names (both active links and filters) from the dropdown menu lists.
For more information, see “Defining advanced Call Guide actions” on
page 141.
9 Click Add Action (or click Modify Action).
The Call Guide action appears in the Current Actions list.
For active link guides, if the guide being called is not connected to the form
where the active link is running, a new window opens.
Enhancing performance of table loops
With a large number of records, you might see slow performance in the table
loop, especially as more records are selected. The following list suggests some
tips for improving performance:
Use data chunking in the table field. For example, in the Advanced Display
tab of the Field Properties window, set the size of the chunk to 50. This
means that the AR System processes only 50 records at a time.
If you are not using data chunking, you could specify a maximum number
of rows to be displayed in the table field, for example, 50. To set this
property, enter a number of maximum rows in the Table Property tab of
the Field Properties window.
140 Chapter 5—Defining guides and guide actions
Workflow Objects
For more information about working with table fields, see the Form and
Application Objects guide.
In BMC Remedy User, set the Limit Number of Items Returned to some
specified number, for example, 500 (by choosing Tools > Options >
Behaviors).
Make sure you define a Run If condition in your active link. Otherwise, the
design of the table loop actually goes through every single record in the
table and check against the active links that are associated with that table.
Limit the active links in the table loop to run only against rows that are
selected. To do so, append `$ (backquote character followed by a dollar
sign) to the end of the names of the active links contained within the table
loop guide. (You do not need to change the name of the active link that
calls the guide, the names of the table loop actions, or the name of the
active link guide referenced by the call guide.)
Defining advanced Call Guide actions
You can define advanced call guide actions.
With active links, you can provide enhanced functionality beyond calling
guides from a hardcoded server and guide defined in the workflow action.
Based on values that workflow or users enter into certain fields, you can
dynamically select which server and guide you are calling.
With filters and escalations, you are somewhat more restricted. Filters and
escalations cannot have a dynamic server. But based on values that
workflow or users enter into certain fields, you can dynamically select
which guide you are calling.
Guide actions 141
BMC Remedy Action Request System 7.0
Figure 5-4: Using dynamic workflow to call guides
For example, the Calling Guides form (as shown in Figure 5-4) contains two
fields (server and guide) that can be hidden or display-only. The values you
enter into these fields (for example, they could come from a Set Fields action)
determine at runtime which source server and guide are used as sources in
the Call Guide action. Administrators might prefer to hide this functionality
from users altogether and use the Window Loaded execution condition
instead.
In this example, if you opened the Calling Guides form in BMC Remedy User
and entered cordova as the server and Called Guide as the guide, then clicked
Button, the advanced Call Guide action would execute. If the guide that is
dynamically defined does not belong to the current form, the Called Guide
Form window opens in Submit (New) mode.
142 Chapter 5—Defining guides and guide actions
Workflow Objects
To define advanced call guide actions
1 Select Advanced in the Call Guide action.
The window changes so that you no longer select a server and guide from the
Call Guide field but now you can enter “dynamic” server (active links only)
and guide names.
Figure 5-5: Advanced functionality of Call Guide active link action
Select the Advanced
check box
These fields represent the dynamic names of a server and guide that the active
link would acquire at runtime from workflow or information that a user
would enter into certain fields.
Use the boxes to enter field references or keywords for the server and guide
names. These fields come from the reference form (for example, Calling
Guides) that you chose on the Basic tab and are typically hidden. The
dynamic server and guide are not actually used at runtime; the fields you pick
are used only to build the workflow.
2 In the Dynamic Server Name (active links only) and Dynamic Guide Name
fields, enter a field (or choose a field or keyword from the list) that will specify
dynamically which server and guide are used.
Guide actions 143
BMC Remedy Action Request System 7.0
The server and guide you choose will appear in their variable format. For
example, if you choose the field labeled server from the Dynamic Server
Name list, it appears as $server$.
The server and guide that a user (or workflow) enters into those dynamic
fields will be used as the source server and guide that is invoked when the Call
Guide action executes:
For active links, you must enter values into the Dynamic Server Name and
Dynamic Guide Name fields.
For filters, you must enter a value only into the Dynamic Guide Name
field. You cannot choose a different server. Filter execution does not allow
the use of a guide on a different server.
3 Click Add Action (or click Modify Action).
The Call Guide action appears in the Current Actions list.
The Exit Guide active link or filter action
Use the Exit Guide action to terminate the current guide and, optionally, all
of its calling guides.
To define the exit guide active link or filter action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Exit Guide.
Figure 5-6: Exit Guide active link action
Clear this check box to
prevent all guides from
closing.
144 Chapter 5—Defining guides and guide actions
Workflow Objects
3 Select or clear the Close all guides on exit check box. If this check box is:
Selected—All of the guides running will exit when the active link or filter
is executed.
Cleared—Only the current guide running will exit when the active link or
filter is executed. (Default)
4 Click Add Action (or click Modify Action).
The Exit Guide action appears in the Current Actions list.
The Go To Guide Label active link or filter action
Before creating a Go To Guide Label action for the appropriate guide, use the
Add Label button of the Guide window to insert a label before the active link
or filter that you want to execute. See “To define active links or filters in a
guide” on page 133.
Use the Go To Guide Label action to redirect the flow of execution within a
guide to a specific active link or filter. This action can be useful when you
want to perform a step multiple times. For each time that you want to repeat
a step or series of steps, a Go To Guide Label action returns you to the specific
active link or filter in a series.
To define the Go to Guide Label active link or filter action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Go To Guide Label.
The Guide Label field appears. The following figure shows this field and an
example of how a Go To Guide Label active link action might look after you
complete the remaining steps in this procedure.
Guide actions 145
BMC Remedy Action Request System 7.0
Figure 5-7: Go To Guide Label active link action
3 In the Guide Label field, enter the name of the label that precedes the active
link or filter with which you want to begin.
If you have not already inserted a guide label before the active link or filter
with which you want to begin, you must modify the appropriate guide object
in this way before you can complete this step.
4 Click Add Action (or click Modify Action).
The Go To Guide Label action appears in the Current Actions list.
The Wait active link action
Use the Wait action to suspend a guide in BMC Remedy User so that the user
can interact with a field. After making a response, the user can continue the
guide by pressing Tab or by clicking the appropriate button. The user can
also terminate the guide during a Wait action.
Note: Interactive guides cannot be used on the Web.
The Wait action has no effect when executed outside of a guide.
Use the following sequence of active links to create a navigational training
guide:
Change Field (Set Focus)
Message (Prompt)
Wait
146 Chapter 5—Defining guides and guide actions
Workflow Objects
For a detailed example on creating a navigational (or interactive) guide, see
“Creating interactive guides” on page 156.
To define the Wait active link action
1 Click the If Action tab or the Else Action tab.
2 From the New Action list, select Wait.
The Label for Continue Button field appears. The following figure shows this
field and an example of how your Wait active link action might look after you
complete the remaining steps in this procedure.
Figure 5-8: Wait active link action
3 In the Label for Continue Button field, enter the text you want to appear on
the Continue button in the prompt bar.
Common labels include “Continue” (the default), “Next Step,” and “Finish.”
4 Click Add Action (or click Modify Action).
The Wait action appears in the Current Actions list.
Guide actions 147
BMC Remedy Action Request System 7.0
Active link guides
Here are some possible uses of active link guides:
Type of guide
Possible uses
Interactive guides Walk users through filling out a form or direct users through
each step of a procedure, much like a wizard. (These are also
known as “navigational guides.”) Interactive guides can be
implemented in BMC Remedy User, but not through a
browser.
Computational
guides
Used for manipulating data as a background process without
any user interaction. (These are also known as “procedural
guides.”) A good example of a procedural guide is one that uses
workflow to step through the rows that appear in a table field.
For more information, see “Using active link guides in clientside table fields” on page 153.
Entry point
guides
Allows users access to sophisticated tasks through the
Application List field on your Home Page form. For example,
an entry point guide will allow users to access reports, or
Modify or Display windows. For more information, see the
Form and Application Objects guide.
An Active Link guide can be executed through the Open dialog box in BMC
Remedy User (File > Open > Classic), through workflow, or through an
email attachment that users can then drag to their Desktop as a shortcut.
The following actions used to control the execution of guides:
Call Guide active link action—Executes or invokes a guide. For example,
you could create a button on a form that uses the Call Guide active link to
invoke a guide.
You can use the Call Guide active link action to execute a guide from any
client-side workflow, even from inside another guide. If a guide calls
another guide on the same form, the result is a stack of guides. Control is
not returned to the calling guide until the called guide exits or the nested
guide executes a wait action. For more information about the Call Guide
action, see “The Call Guide active link or filter action” on page 138.
148 Chapter 5—Defining guides and guide actions
Workflow Objects
Go To Guide Label active link action—Breaks a guide’s normal sequence.
When the Go To Guide Label active link is executed inside a guide, the
action that follows the label will be executed next. You can use this action
to create data validation in a guide to make sure that users entered the
correct information on a form. For example, if a user enters a number that
is not recognized in the underlying form, the guide opens a warning dialog
box for the user. When the user clicks OK in the dialog box, the guide
continues for the user to enter the correct integer. When the user finishes
working through all the steps in the guide, the guide closes.
You could also create a guide that invokes other guides if the user has
entered wrong information. When the user has completed all the
necessary information, the second guide closes and enters the correct
information back into the first guide.
The following figure shows an example of an interactive guide using the
Go To Guide Label.
Figure 5-9: Guide using Go To Guide Label active link action
For more information about the Go To Guide Label action, see “The Go
To Guide Label active link or filter action” on page 145.
Active link guides 149
BMC Remedy Action Request System 7.0
Exit Guide active link action—Exits a guide. The Exit Guide action is
helpful if users enter incorrect information into a guide or if conditions
for the guide to run are not met. Under these conditions, you might decide
to exit the guide or all guides.
Typically, you do not need to use the Exit Guide action to quit the guide.
A guide that has completed its actions successfully exits without using the
Exit Guide action.
For more information about the Exit Guide action, see “The Exit Guide
active link or filter action” on page 144.
How active links interact with guides
Most of active link Execute On conditions do not interact with a running
guide. If the Execute On condition occurs while a guide is running, active
links are executed normally, independent of the guide. For example, if a
guide executes a Run Macro action that sends a request, the Execute On
Submit condition is processed before the next guide action. However, active
links that are available to the form and independent of the guide can interact
with active links contained in a guide. See the following table for a summary
of how active links interact in guides.
You can use the $GUIDE$ keyword in qualifications to determine whether an
active link is executing as part of normal workflow or in the context of a
guide. When $GUIDE$ = $NULL$, the guide is not running. Otherwise, the name
of the current guide is the value of the $GUIDE$ keyword.
For more information about qualifications, keywords, and active links, see
Appendix A, “Operators, wildcards, keywords, and NULL values.”.
Execute On
Condition
Interaction
Submit
These conditions can be triggered only when a guide is
executing a Wait action, or as the result of a Run Macro
action that the guide executes. The conditions are executed in
sequence.
After Submit
Search
Modify
After Modify
Display
150 Chapter 5—Defining guides and guide actions
Workflow Objects
Execute On
Condition
Interaction
Window Open
Active links with this condition are executed during guide
execution. Thus, if a guide action causes a window to open,
any active links tied to the Window Open condition are
executed before the next guide action is executed.
If a guide is executed by an active link tied to a Window Open
condition, then the guide is initialized, but not started
because the user interface is not yet visible. Next, any other
active links with the Window Open condition are executed,
which is followed by any set defaults processing (described in
the following row). When the interface is set up, the guide
executes.
Set Default
This is the most subtle of all conditions. There are several
cases to consider:
Case 1: Active links tied to a Set Default condition are
executed when a guide is waiting and the user chooses the Set
to Defaults menu item.
Case 2: A guide is executed by an active link tied to a Window
Open condition. In this case, the guide is initialized, but not
started because the user interface is not yet visible. After the
guide has initialized, the active links tied to the Set Default
condition execute. After the field list and display symbols are
set up, the guide is executed.
Case 3: A guide is executed from the Open dialog box in BMC
Remedy User. In this case, the guide is initialized first, and
then the guide opens the form. The Window Open condition
occurs and is followed by the Set Default condition. Lastly,
the guide executes.
Case 4: When the “on new” or “on search” behaviors are set
to “set fields to default values,” any active links tied to the Set
Default condition are executed when a guide is waiting or as
the result of a Run Macro action executed by the guide (after
a send or a search).
Un-Display
Window Close
If you close the form on which a guide is running, the guide
is terminated. Active links tied to the Window Close
condition are executed before the guide terminates. Usually
this occurs while a guide is waiting, but it can happen when a
guide executes a Run Macro action.
Active link guides 151
BMC Remedy Action Request System 7.0
Execute On
Condition
Interaction
Button/Menu Item Active links that have this condition execute when a guide
waits. BMC Remedy User treats form buttons as fields. If you
click a button while a guide is in a wait, the guide displays the
“user is off the guide” dialog and executes the active links tied
to the button.
Return/Table Dbl- These conditions can be triggered only when a guide is
Clk
executing a wait action. If the field focus is changed by an
Menu/Row Choice action associated with the On Return trigger, then the Wait
condition on the guide ends.
Gain Focus
When a guide executes a Change Field Set Focus action, any
active links associated with the field’s Gain Focus condition
execute before the next guide action is executed. When a
guide is in a wait condition, the user cannot change field
focus unless the running guide is terminated.
Lose Focus
When a guide executes Change Field Set Focus action, any
active links associated with the current field’s Lose Focus
condition execute immediately. The newly focused field’s
Gain Focus condition is then processed. After all Lose Focus
and Gain Focus active link processing is completed, the next
guide action is executed. When a guide is in a wait condition,
the user cannot change field focus unless the running guide is
first terminated.
Copy To New
No interaction.
Interval
If an Interval condition executes during an active link guide,
the guide will wait until all the workflow related to the
interval condition is complete before the remainder of the
guide finished.
Event
Active links with this condition are executed during
execution of an event. Thus, if a guide action sends an event,
any active links tied to the Event condition are executed on
the target window before the next guide action is executed.
152 Chapter 5—Defining guides and guide actions
Workflow Objects
Using active link guides in client-side table fields
Active link guides are useful for creating workflow that walks you through
the rows in a client-side table field. (For server-side table fields, see “Using
filter guides in server-side table fields” on page 163.) The workflow will go
through every row in a table and then perform selected workflow actions on
particular rows or sets of rows. For example, you can create workflow to find
a specific row in a table field, then perform actions based on specific criteria.
(For more information about optimization, see “Enhancing performance of
table loops” on page 140.)
You can also build workflow to:
Skip rows, based on mathematical calculations upon a field.
Find a row that has changed values and perform an action on it, using the
$ROWCHANGED$ keyword.
Find a row that has been selected and perform an action on it, using the
$ROWSELECTED$ keyword.
For more information about keywords, see Appendix A, “Operators,
wildcards, keywords, and NULL values.”
The following procedure is for a simple loop that searches through all the
rows of a table field until it finds a ticket with a specific user’s name on it. The
workflow then sets a field with values from a column in the table field.
Note: This procedure assumes you already know how to create forms, fields,
workflow, and guides.
To create a guide that walks you through a table field
1 Create a form (for example, Loop Test) and add two additional fields:
A button field (for example, Button).
A table field that includes at least the following fields as columns in the
Table Property tab:
Submitter field (Column1)
Request ID (Column2)
2 Create an active link (Loop Test SF Active Link) with a Set Fields action.
Active link guides 153
BMC Remedy Action Request System 7.0
3 Configure the Basic tab of the active link:
Run If: ‘Column1’ = $USER$
The test here is to execute the active link only if the value of the Submitter
field is set to the person who is logged in to BMC Remedy User.
4 Configure the If Action tab and create the first action:
Action: Set Fields
Name: Short Description
Value: $Column2$
Here you will be filling the Short Description field with the Column2 value,
which is the Request ID field.
5 Create an active link guide (Loop Test Guide) and add Loop Test SF Active
Link to the guide.
6 Create an active link (Loop Test Active Link Button).
7 Configure the Basic tab of the active link:
Execute On: Button/Menu Item
Field: Button
8 Create an active link action.
Action: Call Guide
Call Guide Form Name: Loop Test Guide
9 Select the Table Loop check box.
This action will activate the guide and “loop” it through the rows in the table
field.
10 Log in to BMC Remedy User as user Demo and open the Loop Test form.
11 As a test, create several tickets, but only one with Demo as the value of the
Submitter field.
12 Click the table field to refresh it. The tickets you just created will appear as
rows.
13 Click the button field on the form.
154 Chapter 5—Defining guides and guide actions
Workflow Objects
The workflow will be triggered and will loop through all the rows in the table
field until it finds a row with Demo as the value of the Submitter field. The
workflow then fills in the Short Description field with the value of the
Request ID field.
Using interactive active link guides
One use of a guide is to help a user navigate through a series of interactive
steps. To the user, a guide looks like any other application that you open in
BMC Remedy User. A guide includes the Stop Guide and Continue buttons,
as shown in Figure 5-10.
Figure 5-10: Interactive guide
When the guide prompts a user for information, the user enters the
information, and then clicks Continue (or presses the Tab key). Users can
quit the guide at any time by clicking Stop Guide.
A guide that walks users through a form depends especially on the Wait active
link action and the prompt bar in BMC Remedy User. To create the typical
steps in a navigation-style guide, use the following active links in this
sequence:
Change Field (Set Focus)—Sets focus to a field and highlights the field.
Message (Prompt)—Provides the user with instructions and information
in the prompt bar.
Active link guides 155
BMC Remedy Action Request System 7.0
Wait—Temporarily suspends the guide while waiting for user input.
These first three active links should be set for every field in the form.
Commit Changes—After the user enters all the information on the form,
saves the information and then creates a request.
Guides can also be used to set up an application environment. For example,
you can create a guide that presets a form with tabs, specific colors, default
field values, and so on.
Finally, you can create a guide that uses dialog boxes, much like a wizard.
This is especially important in a web environment, because the Wait active
link action will not work in a browser. Instead, you must create dialog boxes
for user interaction within the guide. For more information about using a
display-only form as a dialog box, see the Form and Application Objects guide.
Creating interactive guides
The following section describes how you can create an interactive (or
navigational) guide. This example walks you through filling out three fields
in a form. When you click the Help button, the interactive guide is activated.
A halo appears around the first field you must enter information into, and
instructions appear in the prompt bar. After following the instructions, you
click the Continue button for more instructions.
This example uses the Wait and Call Guide actions, but you could easily
include more advanced actions (for example, the Go to Guide Label action).
This procedure assumes you already know how to create forms, fields, and
active link workflow.
Note: Interactive guides are not supported on the Web.
156 Chapter 5—Defining guides and guide actions
Workflow Objects
To create an interactive guide
1 Create a sample form (for example, like the Active Link Guide Form).
Figure 5-11: Base form for creating an active link guide
This form has three required fields that users will fill in with the interactive
guide:
Last Name
Department
Email Address
You activate this interactive guide by clicking the Help button. In step 2, you
will create the active links that walk the users through the guide.
Active link guides 157
BMC Remedy Action Request System 7.0
2 Create and save three active links with Change Field, Message, and Wait
active link actions. You can use the following sample information:
Table 5-1: Interactive guide active links
Last name active link
Department active link
Email address active link
Enter following
information:
Enter following
information:
Enter following
information:
Name: ALG:Last
Name
Execute On and Run
If conditions: None
Name:
ALG:Department
Execute On and Run If
conditions: None
Name: ALG:Email
Address
Execute On and Run If
conditions: None
Change Field action Enter or set the
following information:
Enter or set the following
information:
Enter or set the following
information:
Basic tab
Message action
Wait action
Permissions
Action: Change Field
Field Name: Last
Name
Select Set Focus to
Field.
Action: Change Field
Action: Change Field
Field Name:
Field Name: Email
Department
Address
Select Set Focus to Field. Select Set Focus to Field.
Enter or set the
following information:
Enter or set the following
information:
Action: Message
Text: Type the
requester’s name in
the Last Name field.
Click the Continue
button.
Action: Message
Action: Message
Text: Type the
Text: Type the email
department name in the
address in the Email
Department field. Click
Address field. Click the
the Continue button.
Continue button.
Enter or set the
following information:
Enter or set the following
information:
Enter or set the following
information:
Action: Wait
Label for Continue
Button: Wait
Action: Wait
Label for Continue
Button: Wait
Action: Wait
Label for Continue
Button: Finish
Public
Public
Public
Enter or set the following
information:
These active links are similar in construction. Use the Save As feature to help
you create them more quickly.
Figure 5-12 illustrates a typical active link action.
158 Chapter 5—Defining guides and guide actions
Workflow Objects
Figure 5-12: Typical active link actions for interactive guide
3 Create an active link guide (for example, Incident Guide).
4 Enter the following information in the Basic tab:
Form Name: Active Link Guide Form
Tip: At this point, you could easily create an entry point guide by clicking the
Entry Point check and choosing an active link that opens a window. For
more information, see the Form and Application Objects guide.
5 In the Active Links tab of the active link guide, add the three active links you
just created. Make sure they are in the following order:
ALG:Last Name
ALG:Department
ALG:Email Address
6 Grant the Public group Hidden access permissions to the active link guide.
7 Save and close the active link guide.
Active link guides 159
BMC Remedy Action Request System 7.0
8 Create an active link that calls your active link guide (for example, Call
Incidents Guide).
9 Enter the following information in the Basic tab of the active link:
Form Name: Active Link Guide Form
Execute On Button/Menu Item: Help
10 Create an active link action.
Action: Call Guide
Call Guide: Incident Guide (this guide calls Active Link Guide Form)
11 Grant public permissions to your active link.
12 Save your active link.
13 Test your active link guide:
a In BMC Remedy User, open the Active Link Guide Form form in New
mode.
b Click the Help button.
c Follow the directions in the Prompt Bar, as shown in Figure 5-13.
Figure 5-13: Interactive guide
160 Chapter 5—Defining guides and guide actions
Workflow Objects
If you do not experience the expected results in the interactive guide, review
the steps for creating the active links or active link guide and correct the
error.
Filter guides
Filter guides are used to create reusable components of filter workflow by
adding computational subroutines within filter processing. This provides for
more sophisticated workflow solutions and allows easier reuse of
functionality between forms.
A filter guide is a list of filters that perform a task on a particular form. You
create the filters before you insert them into a guide. Filters that execute in the
context of guides are not triggered by the same Execute On conditions that
trigger a filter during normal workflow. Filters are evaluated in their order
within the guide, subject to redirection by the way of the Go To Guide Label
action. If a filter used in a guide does have an execution condition, its
execution condition will be ignored.
You use three filter actions to implement filter guides:
Call Guide—Starts the filter guide. Like active link guides, the Call Guide
action can be nested, calling yet another filter guide. The number of nested
Call Guides cannot be deeper than the maximum depth of the filter action
stack. For more information about the Call Guide action, see “The Call
Guide active link or filter action” on page 138.
Exit Guide—Terminates the filter guide. This action will be ignored if it is
not running inside of the filter guide. For more information about the Exit
Guide, see “The Exit Guide active link or filter action” on page 144.
Go To Guide Label—Redirects the flow of execution within a guide to a
specific filter. This action will be ignored if it is not running inside the
guide. If the guide label is not found, this action is ignored as well. For
more information about the Go To Guide Label action, see “The Go To
Guide Label active link or filter action” on page 145.
Filter guides 161
BMC Remedy Action Request System 7.0
Filter guides allow a developer to group a set of filters into a single unit of
work (that is, a subroutine) and call just the filters referenced in sequence
inside the guide without caring about the execution order of other filters.
They also let developers call the filter guide under many different
circumstances tied to multiple different forms. In essence, developers can
create a piece of functionality that can be called as a unit of work, and not care
about the execution order across all filters. In that way, developers can focus
on what the filter guide as a unit of work accomplishes. For example, take the
following filters with their execution orders:
Filter Name
Execution order
A
100
B
102
C
104
D
102
E
110
F
99
By design, each filter will execute in its own execution order, based on which
events trigger the filter action.
By contrast, a filter guide could call these filters, in the following defined
sequence:
Filter Name
A
C
E
This same filter guide can be triggered in different circumstances, at different
times, from different forms.
Note: Filter guides do not affect the “phases” of filter processing. A Set Fields
action will still execute in Phase 1, a Push Fields action in Phase 2, and so
on. For more information about filter phases in AR System, see “Filter
processing in the AR System server” on page 184.
You use essentially the same procedures to create filter guides as you would
active link guides. For more information, see “Defining guide basics” on
page 131.
162 Chapter 5—Defining guides and guide actions
Workflow Objects
Using filter guides in server-side table fields
Filter guides are useful for creating filter workflow that steps through the
rows in a server-side table field. The workflow will go through every row in a
table and then perform selected filter actions on particular rows or sets of
qualifying rows. These qualifications can be built with reference to table
column values.
Because filters run on the server, you cannot use server-side table fields to
highlight rows for display. You cannot select rows on server-side table fields,
like you can on the client side.
Tip: For best performance, combine all operations on a server-side table field
into a single filter guide. This will avoid retrieving the data from the server
more than once.
This table looping functionality only works inside the filter guide. Filters
function only on one AR System server. If a server-side table field points to a
form on a remote server, the filter guide will not work.
You can also perform calculations on the columns of the server-side table
field, using the COLAVG, COLCOUNT, COLMAX, COLMIN, and COLSUM functions inside a
filter guide. Use these functions just as you would with active link guides. You
can also use these functions for standalone filters that are not contained
inside a filter guide.
For more information about table fields and functions, see the Form and
Application Objects guide.
Server-side table field example
The following procedure constructs a simple loop that searches through all
the rows of a server-side table field on a helper form (Form1) until it finds all
the tickets with a specific user’s name on them. The workflow then uses
values from a column in the table field to set fields on a second form (Form2).
The first Set Fields action concatenates all the returned values of the table
field column into a character field; the second action uses the COLCOUNT
function to display the number of columns returned.
Filter guides 163
BMC Remedy Action Request System 7.0
Figure 5-14: Example of server-side table workflow
You could enhance this example by including additional in-line workflow,
for example, notifying a user about the number of rows returned.
Note: This procedure assumes you already know how to create forms, fields,
filter workflow, and filter guides.
To create a filter guide that loops through a server-side table field
1 Create a form (for example, Form1).
2 Create another form (for example, Form2) and add three additional fields:
An integer field to display the number of tickets (for example, Tickets).
A character field to display all the entry IDs of the columns returned (for
example, Concatenated Columns). Align these fields side-by-side so that
the results will show all the tickets for a specific user.
164 Chapter 5—Defining guides and guide actions
Workflow Objects
A table field that includes at least the following fields as columns in the
Table Property tab:
Request ID (Column)
Submitter (Column2)
3 In the Table Property tab for the table field, make sure you reference the
Form1 form in the Supporting Form Info fields.
4 In the Table Property tab, enter the following qualification:
'Submitter' = $Submitter$
You want the table field to show only the tickets created by the submitter
when you display Form2 (see step 19).
Tip: Using this qualification in the table field lets the database do all the
processing work in the record selection, not the AR System server or the
client. In this example, the performance value of server-side table fields is
letting the underlying database select the entries that match the
$Submitter$ field; the AR System server does not see the other entries.
5 (Optional) Hide the table field.
Because you use server-side table fields exclusively for computation, you
should hide them on forms that users interact with.
6 Create a filter (Form2 Set Field) with a Set Fields action.
7 Enter the following information into the Basic tab of the filter:
Form Name: Form2
Now create Set Fields actions in step 8 and step 9.
8 Create a Set Fields action.
Action: Set Fields
Name: Concatenated Columns and Value: ($Concatenated Columns$ +
" ") + $Column$
Here you will concatenate all the returned columns into the Concatenated
Columns field and separate them with a space. $Column$ references the
table column that contains the request IDs.
Filter guides 165
BMC Remedy Action Request System 7.0
9 In the If Action tab, create another Set Fields action:
Action: Set Fields
Name: Tickets and Value: COLCOUNT($Column$)
Here you will use the COLCOUNT function to fill the Tickets field with
the value of how many tickets this user has created.
10 Create a filter guide (Form2 Filter Guide).
11 Enter the following information in the Basic tab of the filter guide:
Form Name: Form2
12 In the Filters tab of the filter guide, add Form2 Set Field to the guide.
13 Create a filter (Form2 Call Guide).
14 Enter the following information in the Basic tab of the filter:
Form Name: Form2
Execute On: Submit
This filter executes when you create tickets in Form2 and then display them.
15 Create a filter action.
Action: Call Guide
Call Guide: Form2 Filter Guide (this guide calls the Form2 form)
16 Select the Table Loop check box, then select the table field on Form2.
This action will activate the guide and loop it through the rows in the table
field.
17 Log in to BMC Remedy User and open the Form1 form in New mode.
18 As a test, create several tickets, but create two or three with John as the value
of the Submitter field.
19 Open the Form2 form in New mode and create a ticket for John.
20 Perform a search for John’s tickets, then click the request in the Results List.
The workflow will be triggered and will loop through all the rows in the table
field until it finds the rows with John as the value of the Submitter field. The
workflow then fills in the rest of the form with the number of John’s tickets
created in the Form1 form. In addition, the entry IDs of the returned
columns are combined together into the Concatenated Columns field.
166 Chapter 5—Defining guides and guide actions
Workflow Objects
Figure 5-15: Tickets returned and columns displayed
If you searched for the requests of other users and clicked on them, the
number of tickets they created in the Form1 form will appear. This simple
procedure used filters in a filter guide to loop through a server-side table field
to count the relatively small number of requests created by a user.
You could use much the same functionality to loop through hundreds or
even thousands of requests in the database, bypassing both the server and the
client. By contrast, you could use client-side processing to calculate this
information, but you also risk slowing down your system.
Server-side table field implementation issues
Keep these server-side table field limitations in mind:
When creating workflow for server-side tables, filters with the Call Guide
action can be defined to loop over table columns. The values retrieved
during the looping will always come from the last row of the table. To
retrieve different values, postfix two special characters ( `! ) on the filters
within the filter guide. Adding these special characters causes your filter to
execute synchronously, instead of deferring into a later filter processing
pass. For example, if your filter within the Filter guide is named FormA:
Push New Entry to Form B, you need to postfix those special characters to
look like this:
FormA: Push New Entry to Form B`!
Filter guides 167
BMC Remedy Action Request System 7.0
Data conversion between values in a column of one type should be able to
be set or pushed to fields of a different type for most data types. But unlike
client-side table fields, there are some limitations in server-side tables for
the following conversions:
CHARACTER to DECIMAL
CHARACTER to REAL
For example, 123.45 six converted to decimal became 0.00, and converted
to real became 0.000000.
On the other hand, 123.45 does convert properly to 123.45 and 123.450000.
Setting values from columns of integer, real, decimal, or currency type
(and sometimes character type) to date or time fields does not yield NULL
for negative values such as -3 or -3.01. Instead, the lowest values of the date
and time type are set.
For example, the lowest value of date fields is 1/1/4713 BC, while the lowest
value of time fields is 12:00:00 AM.
168 Chapter 5—Defining guides and guide actions
Chapter
6
Using buttons and menu bar
items to execute active links
You can set an active link to execute when a user clicks a button in a form or
chooses a menu item from a top-level menu. (The active link can be a button
or a menu item, but not both.) If an active link is executed when a user
chooses a menu item, you can also execute the same active link through a
corresponding toolbar button.
This section discusses how you can use buttons and menu bar items to
execute active links. The following topics are provided:
Understanding how buttons and menu items work with active links
(page 170)
Active links as menu items (page 171)
Changing the order of menu items and toolbar buttons (page 175)
Associating active links with buttons and menu items (page 176)
Deleting buttons and menu items (page 178)
Using buttons and menu bar items to execute active links 169
BMC Remedy Action Request System 7.0
Understanding how buttons and menu items work
with active links
Buttons and menu items are fields in AR System; you can use them in
workflow as in any other field. For example, an active link can show, hide,
enable, or disable buttons and menu items. Because these fields do not have
data behind them and they are used to control workflow, they are called
control fields.
Figure 6-1: Form with active link buttons and menu bar items
Menu items for executing active links
Toolbar buttons for executing active links
Buttons in form for
executing active links
You can associate more than one active link with a button or menu item. A
good use of this capability is to define active links that execute based on
current conditions, such as the platform on which the tool is running. For
example, you can define an active link to execute only if the tool is running
on a PC.
You could then associate another active link with the same field, this time
defining the active link so that it executes only if the web client is running.
Users on either platform can then perform the same action to execute the
appropriate active link for their platform.
170 Chapter 6—Using buttons and menu bar items to execute active links
Workflow Objects
Figure 6-2: Active links as buttons or menu items
Active Link 1
Active Link 2
Linked to
Control Field
Displayed as
Button
or
Menu Item
Toolbar Button
(optional)
You can create an active link and then add its button or menu item, or you
can add the button and menu item first and then create the active link.
To add a button to a form, see the Form and Application Objects guide.
Active links as menu items
In each form, you can add menus and menu items to the BMC Remedy User
menu bar. Each menu can have menu items, submenus, and menu
separators. Only menu items can be connected to active links.
To add a new menu or menu item
1 Open the form with which you want to work.
2 Choose Form > Edit Menu Bar.
The Edit Menu Bar dialog box appears.
Active links as menu items 171
BMC Remedy Action Request System 7.0
Figure 6-3: Edit menu bar dialog box
3 To add a menu, menu item, or separator entry, click Add Menu, Add Menu
Item, or Add Separator.
This new entry appears in the Menu Bar Layout list. The exact location of the
new entry is determined by the selection when you clicked the button.
Adding a separator produces a separator at the same level as the current
selection.
Adding an entry when you have a menu selected produces a subordinate
entry, unless the menu item is closed, as indicated by a plus symbol (+).
Adding an entry when you have a closed menu (+), or a menu item selected
produces a new entry at the same level as the selection.
The new entry becomes active. Non-separator entries contain the default text
New Menu, which you can replace with an appropriate label. The maximum
length is 80 characters.
4 To add more menus, menu items, or separators, repeat step 3.
5 To designate one character of the menu or the menu item as an accelerator
key, enter a single ampersand (&) before the character in each menu or menu
item. For example, if you want to create a menu labeled AR &System, the letter
S is underlined in the menu to indicate that it is an accelerator key for that
item.
172 Chapter 6—Using buttons and menu bar items to execute active links
Workflow Objects
When creating accelerator keys, make sure that you do not choose a letter
that is used by other menus on the menu bar. Do not duplicate the choices
for menu items in your menu.
To use the accelerator keys with a toolbar menu, users need to press
Alt+<underlined_menu_letter>+<underlined_menu_item_letter>.
You can also perform the following actions:
To modify a menu or a menu item, select the appropriate entry in the
Menu Bar Layout list, and then edit the text in the Label field.
To expand or contract all menu hierarchies, click Open All or click
Close All.
These buttons control your view of the menu definition, not how the
menu appears in BMC Remedy User.
To delete a menu, menu item, or separator, select the appropriate entry in
the Menu Bar Layout list, and then click Delete.
Child menu entries are deleted when you delete the parent menu entry.
To change the order of the menu items, see “Changing the order of menu
items and toolbar buttons” on page 175.
6 In the Menu Item Help field, enter text that explains the function of the
menu item.
You must select a menu item to enable the Menu Item Help field. The text
appears on the status bar in BMC Remedy User.
7 Select or clear the Hide and Enable check boxes to specify the initial state of
the selected menu entry.
Hide
If the check box is:
Selected—The menu entry cannot be seen in the user’s view.
Cleared (the default)—The menu entry can be seen in the user’s
view.
Enable
If the check box is:
Selected (the default)—The menu entry is active.
Cleared—The menu entry is inactive.
Workflow can change either setting to either state.
Active links as menu items 173
BMC Remedy Action Request System 7.0
8 To add a toolbar button for a menu item:
a Select the Has Toolbar Item check box, and then click Change Bitmap.
The Choose an image file dialog box appears.
b Select a .bmp file for the toolbar button.
The only image size supported is 16 pixels wide by 16 pixels high.
c Click OK.
9 Click Save to Disk to save the image to another area on the network.
10 In the Tooltip field, enter tool tip text.
This text appears in BMC Remedy User when the user holds the cursor over
the toolbar button.
11 To add a toolbar button to a separator, select the appropriate separator from
the Menu Bar Layout list, and select the Has Toolbar Item check box.
The toolbar separator in BMC Remedy User is platform-dependent, but it is
usually a line or extra space.
12 To control how the toolbar will appear in BMC Remedy User, click
Toolbar Layout to open the Toolbar Layout dialog box.
Figure 6-4: Toolbar layout dialog box
13 To change the position of a toolbar button relative to the other buttons, select
the button in the Toolbar Layout list, and then click the up and down Move
arrows.
If you do not perform this step, the toolbar buttons will appear in no
particular order.
174 Chapter 6—Using buttons and menu bar items to execute active links
Workflow Objects
14 Click OK.
15 To set the remaining menu entry properties, click the Database, Permissions,
Change History, Help Text, and Active Link(s) tabs.
The procedures for these tabs are the same as for buttons and are discussed
in the Form and Application Objects guide.
Changing the order of menu items and toolbar buttons
After you have created menus and toolbar buttons, you can change the order
in which they appear in BMC Remedy User by using the following
procedures.
To change the order of menu items
1 Choose Form > Edit Menu Bar.
2 Click the Menu Bar Layout tab.
3 Select the appropriate top-level menu, submenu, menu item, or
menu separator.
4 To change the order of the menu items in the Menu Bar Layout list, right-
click the item that you want to move, drag it up or down in the menu
hierarchy, and then release the mouse button. A menu appears with the
following options:
Move After
Move Before
Move As Child
Copy After
Copy Before
Copy As Child
Cancel
Note: Different context menu options appear if you simply select the item
without dragging it up or down in the menu hierarchy.
Changing the order of menu items and toolbar buttons 175
BMC Remedy Action Request System 7.0
You then can place the item in the menu hierarchy on the same level or on a
different level.
5 Repeat steps 3 and 4 until the items are in the correct order.
6 Save your changes.
To change the order of toolbar buttons or separators
1 Choose Form > Edit Menu Bar.
2 Click the Toolbar Layout button.
3 Select the appropriate toolbar button or separator.
4 Click the up and down Move arrows to move the toolbar button or separator.
5 Repeat steps 3 and 4 until the items are in the correct order.
6 Click OK in the Toolbar Layout dialog box.
7 Click OK in the Edit Menu Bar dialog box.
8 Save your changes.
Associating active links with buttons and menu items
The Active Links tab of the Button Properties window (Figure 6-5 on
page 177) enables you to choose which active links will be executed with the
button or menu item.
For active links that execute when the user selects a button or menu item, the
user must belong to a group with permission for the active link and for the
button or menu item.
If a user has access to all active links associated with a button or menu
item, but not to the button or menu item itself, the button or menu item
will not be displayed in the form.
If the user has access to the button or menu item, but not to any of its
active links, choosing the button or menu item will not execute the active
link.
For more information about setting button permissions, see the Form and
Application Objects guide.
176 Chapter 6—Using buttons and menu bar items to execute active links
Workflow Objects
Note: You can change how an active link is displayed in a form view by using
the Fields In View dialog box, described in the Form and Application
Objects guide.
To associate active links with buttons and menu items
1 Open the form with which you want to work.
2 Complete one of the following actions:
For a button, open the button properties.
For a menu item, choose Form > Edit Menu Bar, and then select the menu
item.
3 Click the Active Links tab.
Figure 6-5: Button Properties window—Active Link(s) tab
4 From the Active Links on Current Form list, select a display option.
All Active Links
Displays all of the active links in the specified form.
Available Active
Links
Displays only those active links in the specified form that are
not assigned to a button or menu item. (Default)
Associating active links with buttons and menu items 177
BMC Remedy Action Request System 7.0
The active links appear with their execution order number in parentheses,
followed by the active link name, followed by (if applicable) the field name of
the button or menu item to which the active link is connected.
5 To add an active link to a button or menu item, select the active link from the
Active Links on Current Form list, and then click Add.
If the active link is already associated with another button or menu item, you
can break the previous connection and add the new one.
6 To remove an active link from a button or menu item, select the appropriate
active link from the Selected Active Links list, and then click Remove.
Deleting buttons and menu items
Buttons and menu items that are deleted from a form are deleted from the
database.
To delete a button
1 Open the form.
2 Select the button, and then choose Edit > Delete.
3 Save the form.
To delete a menu item
1 Open the form.
2 Choose Form > Edit Menu Bar.
3 Select the item, and click Delete.
4 Click OK to save your changes and close the dialog box.
5 Save the form.
178 Chapter 6—Using buttons and menu bar items to execute active links
Workflow Objects
To delete a toolbar button
1 Open the form.
2 Choose Form > Edit Menu Bar.
3 Select the menu item from which you want to delete a toolbar button.
4 Clear the Has Toolbar Item check box.
5 Click OK to save your changes and close the dialog box.
6 Save the form.
Deleting buttons and menu items 179
BMC Remedy Action Request System 7.0
180 Chapter 6—Using buttons and menu bar items to execute active links
Chapter
7
Workflow processing
This section outlines how workflow is processed on the client side (active
links) and on the server side (filters).
The following topics are provided:
Active link processing (page 182)
Filter processing in the AR System server (page 184)
Tracing active link, filter, or escalation activity (page 196)
Workflow processing 181
BMC Remedy Action Request System 7.0
Active link processing
Active link conditions have an order and relationship to one another as well
as to the client and server.
Figure 7-1: Active link processing
Window Open
Set Defaults
Window Loaded
Display
User interaction
with form
User interaction
with request
Return
Menu/Row Choice
Button/Menu Item
Gain Focus
Lose Focus
Search
Submit
Modify
After Submit
After Modify
Un-Display
Interval
Event
Client requests
work from server
Results returned
from server
These execution conditions
are under specific user control
Time-based condition not dependent
on specific client-server interactions
An event can occur at any time
Window Close
182 Chapter 7—Workflow processing
Workflow Objects
Note: The Interval and Execute active link conditions are not included in
Figure 7-1. Interval conditions are time-based and thus not dependent on
specific client-server interactions; “events” can be sent during any change
of application state.
How data is loaded into a form and available to be acted on often depends on
the window mode and how the user interacts with fields on the form. The
order in which active links are processed can help you determine which one
to specify.
Following is an example of an active link process using Window Open:
1 Use the Window Open condition to set field values when the values are
required for workflow processing before the request is actually displayed.
These values are used only as temporary data for validation purposes in
workflow. But when the window opens, the actual values displayed in these
fields will not be this temporary data, but the values specified by the user
preference settings.
2 Use the Display condition for any values you want the user to see when the
request is displayed.
3 Use the Window Open condition to prevent the window from opening and
generating an error message when the user does not have appropriate
permissions.
The way your active link executes can be affected by how users have set their
preferences on the web or their BMC Remedy User Behavior options. Use
caution when using Set Fields or Push Fields actions triggered by Window
Open that rely on specific initial field values. For example, if your active link
relies on default field values appearing, it will not work if users set the option
to clear all fields on Window Open.
More than one active link (or filter) can execute on the same execution
condition, and the output of one can affect another. See the Concepts guide
for more information.
Active link processing 183
BMC Remedy Action Request System 7.0
Filter processing in the AR System server
The AR System server processes filters in an execution order you specify. As
the AR System server considers actions in each filter, it categorizes those
actions into one of three phases. (See “Filter phases” on page 185.) In general,
actions are carried out such that database operations are deferred until after
all actions that modify the database have been performed. At that point, a
single database transaction is opened and all the database operations are
performed. This keeps transaction time and table and row locks in the
database to a minimum.
Some complex applications, however, require database operations to be
performed immediately. For example, an application might be used as a
subsystem of another application, where the results of the subsystem’s work
are needed immediately by the calling application. For more information, see
“Overriding filter processing phasing” on page 192.
Tip: You can combine the Filter, SQL, and API logs to “see” how AR System
interacts with the database and how the different phases interact with each
other, especially if you are creating complicated workflow. For more
information about combining log files, see the Optimizing and
Troubleshooting guide.
Filter execution order
Execution order determines the order in which filters are executed. When
you create a filter, you assign it an execution order value. If one filter has a
lower execution order than another, the actions for the first filter will be
executed or queued before the actions for the second one.
184 Chapter 7—Workflow processing
Workflow Objects
Filter phases
Actions within filters are carried out in one of three phases. All phase 1
actions are carried out immediately. Phase 2 and phase 3 actions are queued
to be carried out later. See “Filter processing example” on page 187.
Using a phased approach to filter processing helps to make sure the following
actions occur:
Notifications are sent and that processes are run only after the database
operations are successful. If any database operation fails, all subsequent
actions are suppressed, and database changes are rolled back. So, the
system defers to a final phase the operations that should not run until
database transactions have been committed and there is no chance that a
rollback will occur.
For example, you might create a filter to notify Shipping that a purchase
order is ready to be fulfilled. If, during the filter processing, an error
occurs, the chain of events will be rolled back, and the transaction will not
be committed to the database. Without phases in filter processing,
Shipping would be notified, and the equipment would be sent, but no
record of the task would be committed to the database.
All data values are complete and available to the notification that is sent as
well as to Push Fields operations that create related records.
Obtaining a write lock (which is an exclusive lock) for a Push Fields
operation is delayed until the point at which a write is performed to the
main data table. This shortens the duration of the exclusive portion of the
transaction, and improves throughput.
Phase 1 actions
The following phase 1 actions are always performed as soon as they can be:
Call Guide
Exit Guide
GoTo
Go To Guide Label
Log to File
Message
Set Fields
Filter processing in the AR System server 185
BMC Remedy Action Request System 7.0
Phase 2 actions
Phase 2 actions are queued when they are encountered and performed after
all phase 1 actions from all filters execute. If a phase 2 action triggers more
phase 1 actions, then those phase 1 actions are performed before the next
phase 2 action. If a phase 2 action triggers more phase 2 actions, then they are
added to the end of the phase 2 queue.
Phase 2 actions include:
Push Fields
Direct SQL
Phase 3 actions
Phase 3 actions do not include any database interaction. All phase 3 actions
encountered are queued and performed after all phase 1 and phase 2 actions.
Phase 3 actions include:
Notify
Run Process
DSO
Phase 3 actions can fail and not affect the operation’s success.
How AR System processes filters
The following diagram illustrates how AR System processes filters.
186 Chapter 7—Workflow processing
Workflow Objects
Figure 7-2: Filter processing
Phase 1
Execute action
Filter fires
Is it phase 1, Phase 2
phase 2, or
phase 3?
Look at action
Phase 3
Yes
Is there
another
action?
Put action on
phase 2 queue
No
Put action on
phase 3 queue
Yes
Look at
phase 2 queue
Any
phase 2
actions?
Yes
Does this
action fire
a filter?
Execute action
No
Is there
another action
in the queue?
No
Yes
No
No
Look at
phase 3 queue
Any
phase 3
actions?
Is there
another
action in the
queue?
Yes
Execute action
No
Finished
processing
Yes
Filter processing example
Suppose we have form A, form B, and form C.
Form A has two filters, F1 and F2, that execute when form A is modified.
Filter F1 on form A has the following attributes:
Execution order 1
Set Fields action (A1)
Push Fields action (A2) to form B
Notify action (A3)
Another Set Fields action (A4)
Another Push Fields action (A5) to form C
Filter processing in the AR System server 187
BMC Remedy Action Request System 7.0
Filter F2 on form A has the following attributes:
Execution order 2
Set Fields action (A6)
Notify action (A7)
Form B has a filter, F3, that fires when form B is modified. Filter F3 has the
following attributes:
Push Fields action (B1) to form C
Set Fields action (B2)
Notify action (B3)
Form C has no filters.
The following figure and steps illustrate the filter processing in the example.
188 Chapter 7—Workflow processing
Workflow Objects
Figure 7-3: Filter processing example
Filter F1 fires
(form A)
Filter F3 fires
(form B)
A1
Begin processing
phase 1 actions
A2
to P2 queue
A3
to P3 queue
B1
Process P1 actions
for this form
B2
A4
A5
to P2 queue
B3
to P2 queue
Filter F2 fires
(form A)
to P3 queue
B1
Resume processing
P2 queue
B3
Last phase 2 action
A5
Begin processing
phase 3 actions
A3
A6
A7
A2
Last phase 1 action
for this form
A7
to P3 queue
Begin processing
phase 2 actions
Processing
Complete
triggers filter F3
Key
Phase 1 (P1) action
Phase 2 (P2) action
Phase 3 (P3) action
action executed
Filter processing in the AR System server 189
BMC Remedy Action Request System 7.0
Step 1 The server acts on the filters by execution order, and for each filter it
examines all of the actions to be performed. For filter F1, the server performs
action A1 immediately because it is a phase 1 action. It puts action A2 on the
phase 2 queue. It puts action A3 on the phase 3 queue. It then performs
action A4 because it is a phase 1 action. Finally, it puts action A5 on the phase
2 queue.
Step 2 The server then moves on to the second filter, F2. It performs A6 immediately
because it is a phase 1 action. It puts action A7 at the end of the phase 3 queue.
Step 3 Having performed all available phase 1 actions (A1, A4, and A6) the server
performs the first action on the phase 2 queue, A2.
Step 4 A2 modifies an entry on form B. Form B’s filter, F3, fires when the form is
modified. The server examines all of the actions to be performed by filter F3.
The server puts action B1 at the end of the phase 2 queue. It performs action
B2 immediately because it is a phase 1 action. It puts action B3 at the end of
the phase 3 queue.
Step 5 After performing B2, the server has no more phase 1 actions, so it performs
the next actions on the phase 2 queue, B1 and B3. Those actions do not cause
any filters to fire.
Step 6 After performing all actions on the phase 2 queue the database transaction is
committed. At this point, the operation will succeed.
The database transaction means the operation fails if any phase 1 or phase 2
action fails, because the DB transaction is rolled back. It also means that if all
phase 1 and phase 2 actions succeed, the operation succeeds even if a phase 3
action fails. So, in the example if one of the notifications could not be sent for
some reason, the modify operation would still have succeeded.
Step 7 The server then performs the actions on the phase 3 queue—A5, A3, and A7.
The following table summarizes the phase to which each action belongs and
in what order each action was carried out.
Phase
Actions (in order of execution)
Phase 1
A1
A4
A6
Phase 2
190 Chapter 7—Workflow processing
A2 (fires filter F3)
Workflow Objects
Phase
Actions (in order of execution)
Phase 1
B2 (from filter F3)
Phase 2
B1
B2
Phase 3
A5
A3
A7
If you receive an error anytime while the actions are running, all processing
stops, the database will roll back the changes, and you will receive an error
message.
Filter phasing exceptions
There are exceptions to the phasing process:
For get and delete actions, phase 1 and phase 3 actions occur together.
For get operations, there is generally no database change, so the actions
need not be phased. (Note that there might be database changes as the
result of Push Fields actions that the get operation triggers.)
For delete operations, you cannot defer actions because the delete action
removes the current record, so the record would be unavailable for the
actions later. The subsequent actions need to run when the data is still
present.
Filter processing in the AR System server 191
BMC Remedy Action Request System 7.0
The following tables further describe when certain operations are processed.
Filter phasing for Create and Merge operations
1) Filters run (including Phase 1 actions).
2) Create operation. (An entry ID is created.)
Database transaction occurs.
3) Phase 2 actions occur.
4) Phase 3 actions occur.
Filter phasing for Set operations
1) Filters run (including Phase 1 actions).
2) Phase 2 actions occur.
Database transaction occurs.
3) Entry is modified in the database.
4) Phase 3 actions occur.
Filter phasing for Get operations
1) Data is retrieved from the database.
2) Filters run (including all Phase 1 and 3
actions).
3) Phase 2 actions occur.
Database transaction occurs.
s
Filter phasing for Delete operations
1) Filters run (including all Phase 1 and 3
actions).
2) Phase 2 actions occur.
Database transaction occurs.
3) Entry is deleted from the database.
Overriding filter processing phasing
Sometimes, processing filter actions in phases is limiting or inefficient. For
example, an application might be used as a subsystem of another application,
where the results of the subsystem’s work are needed immediately by the
calling application.
You can override phasing for Direct SQL, Notify, Run Process, and
Distributed Server Option actions. If you override Push Fields actions, the
actions take the intermediate values, but the database transaction is deferred.
192 Chapter 7—Workflow processing
Workflow Objects
WARNING: Be very careful about how you use overriding filter processing
phasing. Improper use can produce inconsistent, confusing, and
potentially inaccurate results. It is recommended that you avoid using this
capability unless it is critical to your functionality.
Remember, if you override the phases for a filter, Request IDs and create
dates are not available during a Create operation. Also, a modified date is not
available during a Create or Modify operation ($TIMESTAMP$ might be a suitable
workaround in these situations). Furthermore, if there is a failure in the
server, users might receive notifications for a request that does not really
exist.
Finally, the data values used during a given operation are the data values at
the point at which the action is performed. This data value might not be the
final value for some of the fields. The operation can be performed with
intermediate values instead of the final values that you might expect.
As an alternative, display-only fields are available, and they retain their values
throughout the transaction. If you need to have an intermediate value at a
later stage, storing it in a display-only field for later access is often the best
answer. You get all the advantages offered by filter-action phases with respect
to the transaction in progress and still retain the intermediate values.
The following sections discuss two methods for overriding filter processing
phasing:
Using a special override naming convention
Releasing pending operations
Using a special override naming convention
To override the phases for a specific filter, you can make a filter run in-line
(sequentially) by using a special naming convention in the filter name. When
you create or modify the filter, its name must end in a back quote character
[‘] followed by an exclamation point [!]. For example, a filter named
SendNotification that has a Notify action will perform the action in Phase 3.
However, a filter named SendNotification‘! that has a Notify action runs the
notification during Phase 1.
Releasing pending operations
You can use the Application-Release-Pendingrun process command in a filter
or escalation to open a database transaction to perform operations as various
filter actions are performed instead of deferring the operations.
Filter processing in the AR System server 193
BMC Remedy Action Request System 7.0
When you use the Application-Release-Pending command, any database
operations pending when the command is issued are sent to the database. For
example, assume you had a form A that had push field actions that pushed
values into other forms, B and C. When form A pushes field values to B and
C, it causes some database operations to be placed in a pending state. If, after
the push field actions, a Application-Release-Pending command was
executed from form A, the pending database operations representing
changes to B and C would be sent to the database immediately. Any
subsequent processing would then be able to use the changes to forms B and
C.
Note: Because the Application-Release-Pending command is a run process
command, it is a phase 3 operation. If you want AR System to process this
command at some earlier point, you should name the filter that contains
the command according to the naming convention for overriding filter
phasing. See “Using a special override naming convention” on page 193.
See “Table of Run Process and $PROCESS$ commands” on page 242 for
more information about the Application-Release-Pending command.
194 Chapter 7—Workflow processing
Workflow Objects
Error handling
The server reacts to error conditions in various ways, depending on what
operation you are running. In general, errors are handled according to where
you are within filter processing with regard to the database transaction:
If an error is encountered during filter processing, all processing
immediately stops, no further filters or actions will run, and an error is
returned back to the caller.
If the error occurs during a Phase 1 or 2 action but before the database
transaction is completed, the operation is cancelled, the database
transaction is rolled back, and no change is made to the database.
If an error occurs during Phase 3 actions, processing continues, and
changes are not rolled back. However, if you override filter processing so
that your Phase 3 actions will be processed before the database transaction,
errors will be handled according to the “before-transaction-commit”
rules. The error handling itself does not change, but using the override
causes actions that are normally deferred to take place before the database
transaction; therefore, any errors encountered will be handled as an error
before the transaction is complete and will terminate the transaction and
roll back.
To summarize, overriding phasing for a filter moves Phase 3 actions into
Phase 1 actions. Such actions take on the behavior of other Phase 1 actions
(that is, if an error occurs while processing the action, all subsequent filter
processing is halted, and any database changes are rolled back).
Filter processing in the AR System server 195
BMC Remedy Action Request System 7.0
Tracing active link, filter, or escalation activity
You can create a log file of active link, filter, or escalation activity. This option
logs information about active link, filter, or escalation activity for each
operation, including what executed and whether execution was successful.
Active links are executed on the client, so logging is activated in BMC
Remedy User. For information about activating active link logging, see BMC
Remedy User Help.
Filters and escalations are executed on the server. For more information
about filter and escalation logs in BMC Remedy Administrator, see the
Optimizing and Troubleshooting guide.
Note: Errors encountered during the execution of escalations are reported to
the arerror.log. If you have an escalation that fails consistently, a message
will be written to the log every time the escalation is run and fails.
196 Chapter 7—Workflow processing
Appendix
A
Operators, wildcards, keywords,
and NULL values
This section provides descriptions of the operators, wildcards, and keywords
that you can use when defining qualification criteria or building field values.
It also discusses NULL values in fields and how they are used with AR System.
The following topics are provided:
Operators (page 198)
Wildcards (page 202)
Keywords (page 203)
The NULL value, relational algebra, and AR System (page 210)
Operators, wildcards, keywords, and NULL values 197
BMC Remedy Action Request System 7.0
Operators
This section describes how each operator is evaluated when you use multiple
operators in a qualification statement. You can use operators to build logical
expressions. For additional information, see Chapter 3, “Building
qualifications.”
Operator types
The following table lists the operators that you can use when building a
qualification statement.
Operator
Action
AND (&&)
Logical AND of the result of two conditions. (The result is true if both
conditions are true.) For example, 'Status'="New" AND
'Assigned-to'="Andy" finds all new requests assigned to Andy.
You can use the symbol && 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 and all requests assigned to Andy
(no matter what their status). You can use the symbol || (two
vertical lines) instead of the word OR.
NOT (!)
Negates the condition that follows. (If the condition is false, the
result is true.) For example, NOT 'Status'="New" finds all requests
that are not new. You can use the symbol ! instead of the word NOT.
LIKE
Performs a pattern search (see also “Wildcards” on page 202). 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 applies to character and diary fields only. You also use
LIKE with comma separators as the accrue operator in full text
searches. For more information about full text search, see the
Configuring guide.
198 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Operator
Action
EXTERNAL()
Allows for all or part of a qualification to come from a field on the
form. Used in qualifications for active link or filter Run If
conditions, Push Fields or Set Fields actions, table field properties,
and Search type menu definitions. EXTERNAL() is not used in
escalations and flashboard variable qualifications.
Enter a character field name or field ID into the EXTERNAL()
operator, for example, EXTERNAL($field_name$) or
EXTERNAL('50').
EXTERNAL() evaluates to True when:
The field specified contains an expression that evaluates to True.
The field is empty.
The field does not exist or is not a character field.
You can also concatenate expressions, for example,
EXTERNAL($field_name$) AND ‘Submitter’ != $NULL$.
If you use keywords as part of a qualification in a field called by
EXTERNAL(), you must add an escape character (\) to the keywords.
This prevents the keywords from expanding prior to being used in
the qualification.
For example, if you have a table field with a qualification of
EXTERNAL($Qualify Field$)
and Qualify Field is a character field with a value of
(‘Create Date’ < $TIMESTAMP$) AND (‘Login Name’ =
$USER$)
the table field will not produce expected results when refreshed. The
keywords will expand, producing a qualification such as
(‘Create Date’ < 05/22/02 11:00:34 AM) AND (‘Login
Name’ = Demo)
This is not a valid query, since the date/time and character values are
not enclosed in quotation marks. To prevent the keywords from
expanding, write the qualification like this:
(‘Create Date’ < $\TIMESTAMP$) AND (‘Login Name’ =
$\USER$)
In forms viewed on the Web, if EXTERNAL() references a field that
contains a qualification such as $Date 1$ <= ‘Date 2’, you must
add double quotation marks around $Date 1$, like this:
“$Date 1$” <= ‘Date 2’.
Note: In BMC Remedy User, the EXTERNAL operator reads date and
time string from the server's time. On the web, the EXTERNAL
operator reads the date and time string from client's time zone.
For more information, see “Values in qualifications” on page 37.
Operators 199
BMC Remedy Action Request System 7.0
Operator
Action
+
Adds two integer, real, or decimal values.
Adds an integer, real, or decimal interval to a time value. (Real and
decimal values are truncated to an integer value.)
Concatenates two character strings.
For example, 'Create Date'>$DATE$+28800 finds all requests
created after 8:00 a.m. today (where 28800 is the number of seconds
in 8 hours).
-
Performs any of the following calculations:
Subtracts two integer, real, or decimal values.
Subtracts two time values (resulting in an integer).
Subtracts an integer, real, or decimal interval from a time value.
(Real and decimal values are truncated to an integer value.)
For example, 'Create Date'>$DATE$-604800 finds all requests
created within the last seven days (where 604800 is the number of
seconds in one week).
*
Multiplies two integer, real, or decimal 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
more than 50.
/
Divides two integer, real, or decimal values. For example,
'Yearly Expenses'/12>8000 finds all requests where the average
monthly expense is greater than $8,000.
%
Supplies the modulo of two integer values (the remainder of a
division of the values). For example, 'ID'%2=1 finds all requests
with an odd number in the ID field.
<
Matches contents that are less than the value. For example,
'Create Date'<($TIMESTAMP$-86400) finds all requests created
more than 24 hours ago (where 86400 is the number of seconds in
24 hours).
>
Matches contents that are greater than the value. For example,
'Create Date'>"10/31/05 00:00:00" finds all requests created
after midnight on October 31, 2005.
200 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Operator
Action
!=
Matches contents that are not equal to the value. For example,
'Status'!="Closed" finds all requests that are not closed.
Note: If possible, avoid using the != operator when building
qualifications. For more information, see “Tips for improving
system performance when creating qualifications” on page 39.
On Sybase databases, you cannot use the != operator against
unlimited character fields where the database input length
equals 0.
<=
Matches contents that are less than or equal to the value. For
example, 'Salary'<=10000 finds all requests with contents of the
Salary field less than or equal to 10000.
>=
Matches contents that are greater than or equal to the value. For
example, 'Create Date'>="10/31/05" finds all requests created
on or after October 31, 2005.
=
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.
Operator precedence
When you use multiple operators to construct qualification criteria, they are
evaluated in the following order:
1 ( )
2 NOT (!) - (unary minus)
3 * / %
4 + 5 < <= > >= = != LIKE
6 AND (&&)
7 OR (||)
Operators of the same precedence are performed left to right.
You can use parentheses in an expression to override operator precedence.
AR System evaluates expressions inside parentheses first before evaluating
those outside.
Operators 201
BMC Remedy Action Request System 7.0
Wildcards
The following table lists the wildcards that you can use with the LIKE operator
in qualifications.
Wildcard Action
%
Matches any string of 0 or more characters.
Example: J%son matches Jackson, Johnson, Jason, and Json.
_
(Underscore character) Matches any single character.
Example: B_b matches Bab, Bob, and Bub.
[ ]
Matches any single character within a specified set.
Example: [abcf] matches the characters a, b, c, and f.
[-]
Matches any single character within a specified range.
Example: [a-f] matches the characters a, b, c, d, e, and f.
[^]
Matches any single character not within the specified set or range.
Example: [^abcf] matches all characters except a, b, c, and f.
[^a-f] matches all characters except the characters a, b, c, d, e, and f.
Wildcard symbols are interpreted as wildcards only when used with the LIKE
operator; otherwise, they are interpreted literally. To use the percent symbol
(%), underscore (_), or open bracket ([) as an explicit text character within
a LIKE operation, you must enclose the symbol in brackets. For example, [%]
will match the % character, not find 0 or more characters. 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 [^).
You must use the % symbol when you want to include leading and trailing
characters. For example, to match Jill Bobbington, Bobby Fenton, Bob
Compton, and Bob Stone in the Submitter field, enter:
'Submitter' LIKE "%Bob%ton%"
202 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Keywords
The following table lists the keywords that you can use when building a
qualification statement.
Keyword
Value
$APPLICATION$ *
The name (not label) of the currently running application. On web clients,
this keyword is set to NULL when the form is opened from a URL that does
not include the application's name. In BMC Remedy User, this keyword is
set to NULL when the form is opened outside of an application.
$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. For BMC Remedy User, an empty string ("") is
returned.
$CLIENT-TYPE$
The client type of the API program. When used in workflow, this keyword
resolves to a number that corresponds to BMC Remedy User, BMC Remedy
Administrator, DSO, and so on.
The number representations of the different client types are in the ar.h file,
which is located in <install_directory>\api\include. For example, if
you use $CLIENT-TYPE$ in a Run If qualification for an active link, you can
cause the active link to execute only for a mid-tier client (for example,
$CLIENT-TYPE$ = 9).
$CURRENTWINID$ *
Window ID that uniquely identifies the current window in the client
environment. This is the same ID used to send events to this window. The
format and length of window IDs are not constrained. The value returned
from $CURRENTWINID$ should be saved into a display-only character field
with a “database length” of zero (unlimited length).
$CURRENTWINID$ is not the window with focus, but the window ID of the
window in which the active link is running.
$DATABASE$
The type of database used on the current server. This keyword is especially
useful for workflow that is dependent on the database environment.
* This keyword is NULL on the server.
Keywords 203
BMC Remedy Action Request System 7.0
Keyword
Value
$DATE$
For Date/Time fields, the current date (time defaults to midnight). Anything
stored in a date/time field is stored as the number of seconds since UNIX
epoch time, which includes the date and time.
For Date fields, the current date.
For Time fields, $DATE$ evaluates to 12:00:00 AM.
Note: The $DATE$ keyword is not expanded when default values are set. This
allows the value to be set to the date the form is submitted rather than the
date the form is opened. Consequently, the literal keyword is displayed in
the field before the request is submitted.
$DEFAULT$
The default value for the field, if any.
$EVENTSRCWINID$ *
Window ID that uniquely identifies the event source window in the client
environment. The value returned from $EVENTSRCWINID$ should be saved
into a display-only character field with a “database length” of zero
(unlimited length).
$EVENTDATA$
The value that identifies the data of the event.
$EVENTTYPE$ *
The value that identifies the type of the event. The value returned from
$EVENTTYPE$ should be saved into a display-only character field with a
“database length” of zero (unlimited length).
$FIELDHELP$ *
The help text in the Help Text tab of the Field Properties window.
Web applications do not support the $FIELDHELP$ keyword; it will return
NULL.
$FIELDID$
The ID of the field that currently has focus in the client. Returns NULL if the
FIELDHELP keyword is not implemented.
$FIELDLABEL$
The label of the field that currently has focus in the client.
$FIELDNAME$
The name of the field that currently has focus in the client.
$GROUPIDS$
Returns the list of the group IDs of which the current user is a member.
If there are no groups, the value is NULL. If there are groups, the value is a
string displayed in the following format:
;<groupID>;<groupID>;<groupID>;
$GROUPS$
Returns the list of the groups of which the current user is a member.
$GUIDE$
The name of the currently running guide. (The name is $NULL$ if no guide
is running.) This keyword is useful for determining if an active link or filter
is executing as a part of normal workflow or in a guide.
* This keyword is NULL on the server.
204 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Keyword
Value
$GUIDETEXT$ *
The text that is entered under the Help tab of a guide definition.
Web applications do not support the $GUIDETEXT$ keyword; it will return
NULL.
$HARDWARE$
The hardware on which the process is running. This is the name each
hardware vendor has given their hardware:
On UNIX platforms, the name returned by the uname -m command (for
example, sun4c).
On PC platforms, the processor type (for example, PC i486).
You can use this keyword to build filters, escalations, and active links that
execute only if the process is running on an appropriate platform.
Web applications do not support the $HARDWARE$ keyword; it will return
NULL.
$HOMEURL$
The URL of the current page. This option is only valid on web pages. If it is
used in BMC Remedy User, it will return a NULL value.
The $HOMEURL$ keyword enables you to use the relative path to the
application resources when creating workflow. For example, in the Set Fields
action, you can enter the following text for the Set Value for the View Field:
$HOMEURL$/Resources/test.html
The URL is resolved at the runtime and loads a different file without
changing the Set Fields action.
$INBULKTRANSACTION$
Indicates if the current execution is within a bulk transaction. The values
returned are:
0 = False
1 = True
The keyword always expands to a value of 0 on AR System clients.
$LASTCOUNT$
The number of requests returned from the most recent search. You can use
this keyword with any search, including one run from the search window, a
Set Fields operation, a macro, a table refresh, and so on.
Note: The $LASTCOUNT$ keyword is not expanded when default values are
set. This allows the value to be set when the form is submitted rather than
when the form is opened. Consequently, the literal keyword is displayed
in the field before the request is submitted.
* This keyword is NULL on the server.
Keywords 205
BMC Remedy Action Request System 7.0
Keyword
Value
$LASTID$
Upon a successful submit, the keyword contains the Request ID of the most
recently created request during the user’s login environment.
Note: The $LASTID$ keyword is not expanded when default values are set.
This allows the value to be set when the form is submitted rather than
when the form is opened. Consequently, the literal keyword is displayed
in the field before the request is submitted.
$LASTOPENEDWINID$ *
Sent Event keyword that resolves to the ID of the window that was last
opened. Every window that is opened, including children, will be saved as
the last opened window. The value of this keyword will be in affect until
another window is opened.
The format and length of window IDs are not constrained. The value
returned from $LASTOPENEDWINID$ should be saved into a character field
with a “database length” of zero (unlimited length).
$LOCALE$
The language and country code for the specified locale, in the format
<language>_<COUNTRY_CODE>.
To view a list of the language and county codes, open a form, and choose
Form > Manage Views. Click in the Locale column, and open the menu list
that appears.
$NULL$
A null value (no value).
For additional information, see “The NULL value, relational algebra, and
AR System” on page 210.
$OPERATION$
The current operation. See the next table for descriptions of the operation
options.
$OS$
The operating system of the machine on which a process is running. You can
use this keyword to build workflow that executes conditionally based on the
current operating system.
Web applications do not support the $OS$ keyword; it will return NULL.
$ROLES$
For a deployable application, returns the list of roles that map to groups to
which the current user belongs.
$ROWCHANGED$
Evaluates if row in table field has changed:
0 = Not changed
1 = Changed
This keyword is only valid in the context of a table loop guide.
* This keyword is NULL on the server.
206 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Keyword
Value
$ROWSELECTED$
Evaluates if row in table field is selected:
0 = Not selected
1 = Secondary selection
2 = Primary selection
This keyword is only valid in the context of a table loop guide.
Note: The $ROWSELECTED$ keyword is not expanded when default values are
set. This allows the value to be set when the form is submitted rather than
when the form is opened. Consequently, the literal keyword is displayed
in the field before the request is submitted.
$SCHEMA$
The name of the current form.
$SCHEMA-ALIAS$
The singular alias used for a form. This is the form’s active alias, which comes
from one of the request aliases of the active VUI.
$SERVER$
The name of the current AR System server.
$SERVERTIMESTAMP$
For Date/Time fields, the current date and time on the server.
For Time fields, the current time on the server.
For Date fields, the current date on the server.
Note: The $SERVERTIMESTAMP$ keyword is not expanded when default
values are set. This allows the value to be set to the date and time (on the
server) the form is submitted rather than the date and time the form is
opened. Consequently, the literal keyword is displayed in the field before
the request is submitted.
$TCPPORT$
The TCP/IP port of the local AR System server. This keyword is an integer
data type.
Web applications do not support the $TCPPORT$ keyword; it will return
NULL.
* This keyword is NULL on the server.
Keywords 207
BMC Remedy Action Request System 7.0
Keyword
Value
$TIME$
For Date/Time fields, the current time (date defaults to current day).
Anything stored in a date/time field is stored as the number of seconds since
UNIX epoch time, which includes the date and time.
For Time fields, the current time.
For Date fields, the number of seconds since 12:00:00 a.m., which is
converted to a date value.
Note: The $TIME$ keyword is not expanded when default values are set. This
allows the value to be set to the time the form is submitted rather than the
time the form is opened. Consequently, the literal keyword is displayed in
the field before the request is submitted.
$TIMESTAMP$
For Date/Time fields, the current date and time.
For Time fields, the current time.
For Date fields, the current date.
Note: The $TIMESTAMP$ keyword is not expanded when default values are
set. This allows the value to be set when the form is submitted rather than
when the form is opened. Consequently, the literal keyword is displayed
in the field before the request is submitted.
$USER$
The current user login.
$VERSION$
The software version running on the client (active links) or server (filters and
escalations). This keyword includes any applicable patch number.
Note: The $VERSION$ keyword might not be interpreted correctly in
workflow running on pre-5.0 UNIX user tool clients. Use the $OS$
keyword in qualifications to detect UNIX user tool clients.
$VUI$ *
The label of the form view displayed in the active window.
$VUI-TYPE$
The view's platform (such as web or Windows). When used in workflow, this
keyword will be the platform value of the active form view. For filters and
escalations, this keyword resolves to an empty string. This keyword is similar
to $VUI$ except that its value is the VUI type of the active view.
The values for this keyword are NONE, WINDOWS, WEB(RELATIVE),
WEB(FIXED), WIRELESS. The number representations of the different view
platforms are in the ar.h file.
$WEEKDAY$
The current day of the week as a character string.
Note: The $WEEKDAY$ keyword is not expanded when default values are set.
This allows the value to be set to the day of the week the form is submitted
rather than the day of the week the form is opened.
* This keyword is NULL on the server.
208 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
You can use the $OPERATION$ keyword in qualifications to determine
whether the filter or active link should execute on the current operation. For
example, the qualification $OPERATION$="SET" causes the filter or active link
to execute when a request is modified but not when a request appears in
display mode. You can also use this keyword to capture audit information.
For example, setting a field to the value:
"Filter X executed on operation "+$OPERATION$
tells you whether a filter executed during a submit operation (CREATE
returned) or a modify operation (SET returned).
$OPERATION$ Description
Filter execution Form
conditions
mode
CREATE
Occurs while creating a request.
Submit
DELETE
Occurs while deleting a request.
Delete
DIALOG
Occurs while opening a form as a
dialog box.
Dialog
GET
Occurs while retrieving a request for Get
display.
Display
MERGE
Occurs while merging requests.
QUERY
Occurs while searching for requests.
SET
Occurs while modifying requests.
SET ALL
Occurs while modifying selected
requests. (SET ALL is not available
for filters.)
New
Merge
Search
Modify
Modify
Modify
All
Keywords 209
BMC Remedy Action Request System 7.0
The NULL value, relational algebra, and AR System
The value NULL is a unique entity. This section covers how NULL values are
used and interpreted within relational algebra qualifications, and discusses
some special interpretations and overrides used within AR System.
The NULL value
The NULL value is a special value that is different from any valid value for any
data type. It is a legal value in any data type, and is used to represent missing
or inapplicable information. Another way of thinking about NULL is as no
value or the lack of information about the value.
Relational algebra and qualifications involving NULL
All searching in the database uses the SQL language, which is based on the
concepts of relational algebra. The following example illustrates how these
concepts apply to the NULL value.
Suppose there is a form with a selection field called Field X, which allows two
possible states: Yes or No. The form contains 20 records of which Field X is
set to Yes for 7 of them, No for 8 of them, and NULL for 5 of them. When you
search for the records, you receive the following results:
Search for all tickets (without any conditions) results in 20 records
returned.
Search for all tickets where 'Field
Search for all tickets where 'Field
X' = NULL results in 5 records returned.
X' = "Yes" results in 7 records
returned.
Search for all tickets where 'Field
X' = "No" results in 8 records returned.
If you now search for all tickets where 'Field X' != "Yes", you might expect
to receive 13 records returned (8 records where the field is No and 5 where
they are NULL) but you will only receive 8 records. This is correct behavior
according to the rules of relational algebra. NULL is NULL; that is, it has no
value. You must explicitly look for NULL values as they are not implicitly
included in queries that search for values.
210 Appendix A—Operators, wildcards, keywords, and NULL values
Workflow Objects
Relational algebra does not follow Boolean logic, where conditions are either
true or false. Instead, every condition evaluates as one of TRUE, FALSE, or
UNKNOWN. This is called three valued logic. The result of a comparison is
UNKNOWN if either value being compared is the NULL value. Rows satisfy a
search condition if the result of the condition is TRUE. Rows for which the
condition is UNKNOWN do not satisfy the search condition.
To find a row with a NULL value for a field in a search is to explicitly search for
whether the field has a NULL value. Testing for NULL is the only case that a NULL
value will match. So, in the example, to find all entries that are not Yes or are
NULL, the qualification would be
'Field X' != "Yes" OR 'Field X' = NULL
This criteria would have found the 13 records in the example data set.
Any comparison other than equal to and not equal to results in a value of
UNKNOWN. In AND operations, at least one item is NOT TRUE, so the qualification
does not succeed. In OR operations, this clause with NULL is UNKNOW, so the
qualification depends on the result of the other clauses. If all clauses evaluate
to UNKNOWN, the qualification fails as a qualification.
If a NULL value is involved in an arithmetic operation, the result of the
operation is NULL. In other words, any time a NULL value is involved, the entire
operation becomes NULL.
As an example for this functionality, look at the following qualification
('Field A' = 5) OR ('Field B' > 'Field C' + 37)
If Field C has a NULL value, the second clause will evaluate to UNKNOWN. Since
the operation is an OR, the result of the qualification will depend on whether
Field A is set to 5 (success) or not (failure).
An alternative to using NULL is to have a value or state that represents
unknown. Then, you would assign the value of Yes, No, or Unknown. Filters
could be used to assign Unknown if the field is NULL. Then, the field would
always have a value and you would not have the issue about working with a
NULL value.
The NULL value, relational algebra, and AR System 211
BMC Remedy Action Request System 7.0
The NULL value and AR System
In qualifications, a NULL value follows all the characteristics of relational
algebra as defined in the previous section. Since search operations are passed
directly to the database and they base their searches on relational algebra, this
means AR System is based on relational algebra.
However, you are in full control of value assignment and the use of values
within workflow. In these cases, you do not follow the strict rules about NULL
handling. This allows the system to return a result more in line with what is
expected. For example, if you wanted to perform a Set Fields operation where
you assigned a Name field by concatenating the First Name, Middle Initial,
and Last Name field, you might make an assignment like this:
'Name' = $First Name$ + $Middle Initial$ + $Last Name$
If processing used strict relational algebra, and the Middle Initial was NULL,
the name assigned would be NULL. According to relational algebra, a NULL
value within an operation will cause the result of the operation to be NULL.
Instead, AR System treats a NULL value within workflow actions (other than
queries) as follows:
Character, Diary, Timestamp, Selection—An empty string
Integer, Real, Decimal—A value of 0
In the example, the name is assigned the First and Last name without middle
initial.
By treating a NULL value as an empty value rather than as UNKNOWN in a true
relational algebra sense, the end result is what is expected instead of a NULL
value.
212 Appendix A—Operators, wildcards, keywords, and NULL values
Appendix
B
Additional ways to use the Set
Fields action
In addition to the basic instructions described in “The Set Fields active link,
filter, or escalation action” on page 112, this section discusses various ways
you can use the Set Fields active link action to assign a value in a field. The
following topics are provided:
Assigning values by submitting SQL commands (page 214)
Assigning values by issuing requests to a Filter API Plug-In service
(page 219)
Assigning values using function results (page 222)
Assigning values from process results (page 234)
Assigning values by using arithmetic operators (page 237)
For information about assigning values from a DDE request, see the
Integrating with Plug-ins and Third-Party Products guide.
Additional ways to use the Set Fields action 213
BMC Remedy Action Request System 7.0
Assigning values by submitting SQL commands
In addition to setting field values based on AR System data, you can retrieve
data from other sources by submitting SQL queries for use within AR System
workflow. Much like issuing a search to get data from another form, you can
issue an SQL command to retrieve data from any relational database table.
This feature enables you to select data from databases other than AR System
databases, which is useful for integrating AR System with external data
sources.
The ability to submit SQL commands enables you to issue complex queries
to the database. This is useful if customers want to use database features
specific to a particular database platform.
The SQL command you use to set a field value in the Set Fields action has a
different result than the Direct SQL action (see “The Direct SQL active link,
filter, or escalation action” on page 64). In the Set Fields action, you use SQL
to search the database for information and then use the returned values to set
fields. With the Direct SQL action, the SQL command is not expected to
return a value.
If you need to run more than one SQL command, use stored procedures or
functions or any other extension supported by your database. A stored
procedure with a Set Fields action will execute all its commands but will not
return a value.
For the most effective use of SQL commands, you must have a general
understanding of relational databases and a specific understanding of the
relational database underlying your AR System.
WARNING: Because 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 quotes
are reserved for strings, and double quotes are reserved for use with
database object names only.
214 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
To assign a value by submitting an SQL command
1 From the Server Name list, make one of the following selections:
For active links, select the server that contains the value that you want to
retrieve.
For filters and escalations, select the current server.
2 From the Read Value for Field From list, select SQL.
The SQL Command field appears. The following figure shows this field and
an example of how the Set Fields active link action might look after you
complete the remaining steps in this procedure.
Figure B-1: SQL commands in the window
SQL Command
qualification bar and
field
3 In the SQL Command field, enter the SQL command that you want to issue
to the database.
You can type the SQL command, or you can build it by using the
qualification bar and list. Enter only one SQL command for each Set Fields
action. Do not end the SQL command with run or go.
For example, you could enter an SQL command that displays three columns
of data from a table and sorts the data in ascending order based on the first
column:
SELECT BUG_ID, FIRST_NAME, TECHNCN FROM CUSTMR_INFO
ORDER BY 1 ASC
Assigning values by submitting SQL commands 215
BMC Remedy Action Request System 7.0
Use the SQL Command field menu button to insert field values or keywords
in the SQL statement. As shown in the following example, fields and
keywords must be enclosed in dollar signs to indicate that the server should
expand these values before issuing the command:
SELECT BUG_ID, FIRST_NAME, TECHNCN FROM CUSTMR_INFO WHERE
<COL_NAME> = '$<field>$'
You might have to manually insert single quotation marks around the
parameter depending on the content of the expanded value and the context
in which you are using it. Using the example, if <COL_NAME> is a character field
in the CUSTMR_INFO table, you would have to add single quotation marks
around $<field>$ so that the database interprets the expanded field value as
a character string. However, if <COL_NAME> is a numeric field, using the single
quotation marks results in an SQL syntax error. You will also get an SQL
syntax error if you omit the quotation marks but <field> contains character
data.
Note: The syntax that you use must be recognized by the underlying SQL
database on which AR System is running. AR System does not verify the
validity of your SQL command.
4 From the If No Requests Match list, select a handling option to control how
the system responds when the SQL command returns no matches.
For more information about the options in this step, see step 6 on page 116.
5 From the If Multiple Requests Match list, select a handling option to control
how the system responds when the SQL command returns multiple matches.
For more information about the options in this step, see step 7 on page 117.
6 From the Name list, select the field that you are setting with this action.
7 From the Value list, select SQL Result Column, and then select $n$.
The $n$ variable represents the number of a column in the SQL result table
constructed from the results of the SQL command. When the active link,
filter, or escalation executes:
a The SQL command is issued to the database.
b The results of the SQL command are used to construct an SQL result table.
216 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
c The value from column 1 of the SQL result table is loaded into the field
that contains a $1$, the value from column 2 of the SQL result table is
loaded into the field that contains a $2$, and so on.
If an SQL command includes three columns, use a $n$ variable as high as
3. If you specify a $n$ variable that is greater than the number of columns
in the SQL command, a NULL value is returned. If you use an asterisk in an
SQL command, for example SELECT * FROM CUSTMR_INFO, the menu lets
you select an $n$ variable as high as 10. However, if you know that 15
values are returned, entering $14$ will work. Because the first column in
the form table will be used to set the field that contains $1$ (and so on),
you must know the order of the form columns to load the correct data into
the correct field.
Figure B-1 on page 215 illustrates values assigned to fields. If you enter the
same $n$ variables (that is, $1$ in the Long Description field, $2$ in the
Short Description field, and $3$ in the Work Around field) and the SQL
command shown in this illustration, the returned results will create an SQL
result table that looks like the following figure.
Figure B-2: Results returned from SQL command
SELECT BUG_ID, FIRST_NAME, TECHNCN FROM CUSTMR_INFO
1
BUG_ID
5000
5001
5002
2
FIRST_NAME
Mary
John
Mark
3
TECHNCN
Zan
Fran
Tran
Because Figure B-1 on page 215 also specifies that multiple matches should
display a selection list, a selection list of available SQL result table entries will
appear when the active link executes.
If you select the second selection list entry, the contents of BUG_ID will be
loaded into the Long Description field ($1$), the contents of FIRST_NAME are
loaded into the Short Description field ($2$), and so on, as shown in the
following figure.
Assigning values by submitting SQL commands 217
BMC Remedy Action Request System 7.0
Figure B-3: How database columns are inserted into fields
1
BUG_ID
5000
5001
5002
2
FIRST_NAME
Mary
John
Mark
3
SELECT
BUG_ID, FIRST_NAME, TECHNCN FROM CUSTMR_INFO
TECHNCN
Zan
1
Fran
Tran
BUG_ID
5000
5001
5002
2 from the
Values
3Fields and
Database Columns Keywords
FIRST_NAME
TECHNCN
Mary
Zan
5001
John
Fran
Mark
Tran
John
Fran
NULL
Entering a $4$ variable value without an actual fourth column in the SQL
command inserts a NULL value into the field.
Performing the SQL operation
Observe the following general rules for using SQL commands:
You need not use every value that is returned from the SQL command. If
you do not use any values from the SQL command, the Set Fields action
acts like the default selection CURRENT SCREEN (active links) or
CURRENT TRANSACTION (filters or escalation), and the system will
remove your SQL query.
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. If you
need to run a set of commands, create separate actions, or create a stored
procedure and run that. Note that stored procedures do not return values.
Turn on AR System server SQL logging to debug the SQL syntax if it
returns unexpected values or results. A good debugging strategy is to start
an SQL interpreter (for example, isql for Sybase, SQL*Plus for Oracle,
Command Center for DB2, or Microsoft ISQL/w for 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.
218 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
If the SQL operation fails, an AR System error message and the underlying
database error message appear.
You can affect database performance by how an SQL query is written. If
the row has many columns, a SELECT * SQL command can have a greater
performance impact than if you select specific columns. For more
information, see your relational database documentation.
Database security issues
To use SQL commands, familiarize yourself with the specific features of your
underlying database. All SQL commands are issued by the following users:
For Oracle, MS SQL, and Sybase databases, the ARAdmin user (or the
AR System Database User defined during installation).
For Informix databases, the user that controls the arserverd process.
For DB2 databases, the user who installs AR System.
Depending on which database you are using, the data must be accessible to
the user issuing the command. If you are running AR System as one of these
users without permission to access the database, you cannot issue the SQL
command.
To access databases other than AR System databases, use the database name
as part of the SQL command syntax, for example, using MS SQL:
<DatabaseName.owner.table>
getafix.ARAdmin.CUSTMR_INFO
Assigning values by issuing requests to a Filter API
Plug-In service
For filters and escalations, you can pass values from the Set Fields window to
a filter API plug-in service. If the service is running, it will process the request
issued and return the values to the AR System server. These values will then
be loaded into the fields.
Before creating a Set Fields action that uses a filter API plug-in, you must
create a filter API plug-in and perform certain configuration steps. For more
information, see the C API Reference guide.
Assigning values by issuing requests to a Filter API Plug-In service 219
BMC Remedy Action Request System 7.0
To assign values by issuing requests to a Filter API Plug-In service
1 In the Create Filter window, choose Set Fields from the New Action list.
2 From the Server Name list, select the current server for filters and escalations.
3 From the Read Value for Field From list, select FILTER API.
The Filter API window appears. The following figure shows this window and
an example of how the Set Fields escalation action might look after you
complete the remaining steps in this procedure.
Figure B-4: Filter API requests in the window
4 In the Plug-In Name field, enter the name of a filter API plug-in service.
From the list, you can also select a field that contains a service name. The
service name is passed to the plug-in server. If the plug-in server is running
and the service exists, the request will be processed. Otherwise, the Set Fields
action will fail and an error will be logged.
The Plug-In Name list contains all filter API plug-ins that are registered with
the plug-in server. For more information, see the C API Reference guide.
220 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
5 From the Enter Input Values list, enter the values to be passed to the filter API
plug-in.
6 After you create a value, click Add to enter it into the Input Value List.
7 Repeat steps 5 and 6 for each value you want to add.
8 In the Input Value List, make any necessary changes:
Shift the position of a value by clicking the up or down arrows.
Edit a value by clicking it, changing its value, and then clicking Modify.
Change the field type by clicking the description and using the drop-down
list to select a different type, for example, Integer instead of Char.
Remove a row by selecting it and clicking Delete.
These input values will be passed to the filter API.
9 From the Name list, select the field that you are setting with the filter API
data.
10 From the Value list, select Filter API Values, and then select $n$.
The $n$ variable represents the values that are returned by the filter API plugin service, where n is the index of the value in the returned value list. The
menu list provides values up to 20, but you can enter any value. The $n$
variables work much like the values returned by the SQL command, as
described in “To assign a value by submitting an SQL command” on
page 215.
You can combine these values using functions and operations, for example,
$4$ + $3$, that will combine the fourth value and the third value of the
output value list returned by the filter API.
Note: If you do not specify any filter API output values when you save the
filter or escalation, it will be saved as an ordinary Set Fields action. If you
specify an invalid $n$ variable—for example, the filter API returns only
four values but you specify $5$—this action is equivalent to assigning a
NULL value.
Assigning values by issuing requests to a Filter API Plug-In service 221
BMC Remedy Action Request System 7.0
When the filter or escalation executes:
a The service name and input list value are passed from the AR System
server to the plug-in server.
b The plug-in server passes the request to the filter API and waits for a
response.
c The filter API processes the request and passes back the values to the plug-
in server.
d The plug-in server passes the value to the AR System server.
e The AR System server fills the fields with the output values that were
returned by the filter API.
Assigning values using function results
AR System supports a set of functions that you can use in the Set Fields
action. The functions enable you to manipulate data so that you can control
various aspects of values that you are loading into fields. For example, you
can use the UPPER function to convert an ASCII string loaded in a field to
uppercase.
To use a function in a Set Fields operation
1 Create a Set Fields action as described in “To define a Set Fields active link,
filter, or escalation action” on page 114, but enter information in the Name
and Value fields as follows:
a From the Name list, select the field that you are setting with this action.
b From the Value list, click Functions to display a list of available functions.
Information about each function that AR System supports is provided in
the table on the following page.
2 Select the appropriate function.
The function appears in the field with a set of parentheses to its right.
3 For the selected function, enter the arguments within the parentheses.
Information about the arguments that each function requires is provided in
the table on page 224.
222 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
4 Repeat steps 1 through 4 for each field that you want to set with a function.
Note: If the value of any of the arguments of a function is NULL, the result of
the function is NULL (the field is empty). To avoid this result, use a
qualification that verifies the operation and includes a value for all
arguments. For filters and escalations, if you use an empty field as a
parameter in a function, it is considered a NULL value. The exception to this
rule is the third parameter for the REPLACE function. If the third parameter
is NULL, it is interpreted as an empty string.
Specifying arguments that use a comma as a decimal separator
Specifying arguments that use a comma as a decimal separator (as is the case
in a German locale, for example) requires special consideration for the
following functions:
LPAD
RPAD
MAX
MIN
SUBSTR
To specify an argument that uses a comma as a decimal separator
1 Use a hidden, read-only field, and assign a default value to it.
2 Use the appropriate field keywords as arguments.
For example, instead of using SUBSTR($Character Field$, 56, 65) use
SUBSTR($Character Field$, $Integer1$, $Integer2$) where Integer1
and Integer2 are hidden, read-only fields with default values of 56 and 65
assigned to them, respectively.
Assigning values using function results 223
BMC Remedy Action Request System 7.0
The following table lists the functions you can use in a Set Fields action.
Function
Arguments
Return
Description
COLAVG
(column)
any (matches For a given column on a list view, tree view, or
column)
results list table field, returns the average of all
non-NULL row values as a real type.
Following are exceptions:
For char columns, converts the column values to
numeric and averages the numeric values.
If the column type is currency, the average of the
currency value is calculated, and the currency
type is ignored.
If the column type is enum (radio button or
selection), the average of the enum value is
calculated.
COLAVG ignores date/time, date, and time
columns; and returns NULL.
COLCOUNT
(column) or
(table)
int
For a list view, tree view, or results list table field,
returns the total number of rows.
For a column field, returns the total number of
non-NULL rows in a given column.
COLMAX
(column)
any (matches For a given column on a list view, tree view, or
column)
results list table field, returns the maximum value
of the row values.
COLMIN
(column)
any (matches For a given column on a list view, tree view, or
column)
results list table field, returns the minimum value
of the row values.
224 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Function
Arguments
Return
Description
COLSUM
(column)
any (matches For a given column on a list view, tree view, or
column)
results list table field, returns the sum of all values
as a real type.
Following are exceptions:
For char columns, converts the column values to
numeric and sums up the numeric values.
If the column type is currency, the sum of the
currency value is calculated, and the currency
type is ignored.
If the column type is enum (radio button or
selection), the sum of the enum value is
calculated.
COLSUM ignores date/time, date, and time
columns; and returns NULL.
CURRCONVERT
(currency, type,
timestamp)
For a given currency, converts currency to
different type according to new date and
recalculates the functional currency value(s).
Use syntax such as:
CURRCONVERT($<Currency_Field>$,
$<Currency_Field2>.TYPE$,
$TIMESTAMP$)
Use other values for the type and timestamp, such
as a character field and date field. For example:
CURRCONVERT($<Currency_Field>$,
$<Character_Field>$, $<Date_Field>$)
For information about data conversion rules for
currency fields, see the Form and Application
Objects guide.
Assigning values using function results 225
BMC Remedy Action Request System 7.0
Function
Arguments
CURRSETDATE
(currency,
timestamp)
Return
Description
For a given currency, sets new date of currency and
recalculates the functional currency value(s).
Use syntax such as:
CURRSETDATE($<Currency_Field>$,
$TIMESTAMP$)
Use other values for the timestamp, such as a date
field or integer. For example:
CURRSETDATE($<Currency_Field>$,
1026779689)
For information about data conversion rules for
currency fields, see the Form and Application
Objects guide.
CURRSETTYPE
(currency, type)
For a given currency, sets new type of currency and
recalculates the functional currency value(s).
Use syntax such as:
CURRSETTYPE($<Currency_Field>$,
$<Currency_Field2>.TYPE$)
Use other values for the type, such as a character
field. For example:
CURRSETTYPE($<Currency_Field>$,
$<Character_Field>$)
For information about data conversion rules for
currency fields, see the Form and Application
Objects guide.
CURRSETVALUE
(currency, value)
For a given currency, sets new value of currency
and recalculates the functional currency value(s).
Use syntax such as:
CURRSETVALUE($<Currency_Field>$,
$<Currency_Field2>.VALUE$)
Use another field to set the currency value, such as
a decimal field. For example:
CURRSETVALUE($<Currency_Field>$,
$<Decimal_Field>$)
For information about data conversion rules for
currency fields, see the Form and Application
Objects guide.
DATE
(timestamp)
char
Returns the date portion of the time stamp.
226 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Function
Arguments
Return
Description
DATEADD
(datepart,
number, date)
date
For a given date, adds a specified number of days,
weeks, months, or years and returns the new date.
Specify datepart using one of the following
abbreviations, enclosed in double quotation
marks:
Year—yy, yyyy
Month—mm, m
Day—md, dd
Week—wk, ww
The date parameter is the date value to add to.
For example, to add 10 weeks to the 05/20/02, you
would enter:
DATEADD(“ww”, 10, 05/20/02)
DATEDIFF
(datepart,
startdate,
enddate)
int
Depending on the value of datepart (week or
day), returns the number of weeks or days between
the start date and end date.
Specify datepart using one of the following
abbreviations, enclosed in double quotation
marks:
Day—md, dd
Week—wk, ww
For example, to find the number of days between
date1 and date2, you would enter:
DATEDIFF(“dd”, $date1$, $date2$)
DATENAME
(datepart, date)
char
Depending on the value of datepart (month or
day), returns the name of the month or day
corresponding to date.
Specify datepart using one of the following
abbreviations, enclosed in double quotation
marks:
Month—mm, m
Weekday—wd
For example, to find the weekday for December 31,
2003, you would enter:
DATENAME(“wd”, 12/31/03)
Assigning values using function results 227
BMC Remedy Action Request System 7.0
Function
Arguments
Return
Description
DATENUM
(datepart, date)
int
Depending on the value of datepart (year,
month, week, day, or weekday), returns the
numeric value of the year, month (1 to 12), week (1
to 52), day (1 to 31) or weekday (1=Sunday,
2=Monday, and so on). Specify datepart using
one of the following abbreviations, enclosed in
double quotation marks:
Year—yy, yyyy
Month—mm, m
Day—md, dd
Week—wk, ww
Weekday—wd
For example, DATENUM(“mm”, 12/31/03)
returns 12.
DAY
(timestamp)
DECRYPT
(cyphertext, key)
int
Returns the day of the time stamp (1 to 31).
Used in Set Fields filter actions only. Returns the
unencrypted text value of the encrypted text
(cyphertext), using the encryption key (key). The
return value will be 3/4 of the size of the encrypted
string.
For example, to decrypt the string in Field1 using
the key my_key, enter:
DECRYPT($Field1$, "my_key")
To decrypt a string using a key in KeyField, enter:
DECRYPT("String to decrypt",
$KeyField$)
228 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Function
Arguments
ENCRYPT
(plaintext, key)
Return
Description
Used in Set Fields filter actions only. Returns the
encrypted value of a text string (plaintext), using
the encryption key (key).
The output is limited to the size of the field used
for output, including the base-64 encoding.
Therefore, you are limited to encrypting a string
that is 3/4 the size of the output field.
For example, to encrypt the string in Field1 using
the key my_key, enter:
ENCRYPT($Field1$, "my_key")
To encrypt a string using a key in KeyField, enter:
ENCRYPT("Word to encrypt", $KeyField$)
HOUR
(timestamp)
int
Returns the hour of the time stamp (0 to 23).
LEFT
(char,int)
char
For single-byte languages. Returns the left-most
bytes of the first parameter (char) up to the
number of bytes indicated by the second parameter
(int).
For example, to set the value of a field to the first
ten bytes of the Submitter name, enter:
LEFT($Submitter$,10).
LEFTC
(char,int)
char
For single-byte or multi-byte languages. Returns
the left-most characters of the first parameter
(char) up to the number of characters indicated by
the second parameter (int).
For example, to set the value of a field to the first
ten characters of the Submitter name, enter:
LEFTC($Submitter$,10).
LENGTH
(char)
int
For single-byte languages. Returns the number of
bytes in the string (char).
LENGTHC
(char)
int
For single-byte or multi-byte languages. Returns
the number of characters in the string (char).
LOWER
(char)
char
Returns all characters in the string (char) as
lowercase characters.
Note: No conversion will be performed to double-
byte alphabets.
Assigning values using function results 229
BMC Remedy Action Request System 7.0
Function
Arguments
Return
Description
LPAD
(char,int,char)
char
For single-byte languages. Returns the value that
results from padding the first parameter (char) to
the left with the value of the third parameter (char)
so that the resulting value is the length (in bytes) of
the second parameter (int) or the length of the
original string, whichever is longer.
For example, if you want the results of a Set Fields
operation to be a 15-byte value with the prefix
LEAD, followed by zeros, and ending in the
contents of the integer field Call #, enter:
LPAD($Call #$,15,"LEAD00000000000").
If the Call # field contains the number 947, the
result of the Set Fields action will be
LEAD00000000947.
LPADC
(char,int,char)
char
For single-byte or multi-byte languages. Returns
the value that results from padding the first
parameter (char) to the left with the value of the
third parameter (char) so that the resulting value is
the length (in characters) of the second parameter
(int) or the length of the original string, whichever
is longer.
For example, if you want the results of a Set Fields
operation to be a 15-character value with the prefix
LEAD, followed by zeros, and ending in the
contents of the integer field Call #, enter:
LPADC($Call #$,15,"LEAD00000000000").
If the Call # field contains the number 947, the
result of the Set Fields action will be
LEAD00000000947.
LTRIM
(char)
MAX
(any,any[,any]...) any (matches Returns the maximum value of the set specified.
input)
The data type of all values must match for the
result to be meaningful.
char
Returns the value of (char) after deleting any blank
spaces and tabs to the left.
For example, to check the current time and the
escalation time and return only the greater (latest)
value of the two, enter:
MAX ($Escalate Date$, $TIMESTAMP$).
230 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Function
Arguments
Return
Description
MIN
(any,any[,any]...) any (matches Returns the minimum value of the set specified.
input)
The data type of all values must match for the
result to be meaningful.
For example, to check the current time and the
escalation time and return only the lower (earliest)
value of the two, enter:
MIN ($Escalate Date$, $TIMESTAMP$).
MINUTE
(timestamp)
int
Returns the minute of the time stamp
(0 to 59).
MONTH
(timestamp)
int
Returns the month of the time stamp
(1 to 12).
REPLACE
(char,char,char)
char
Returns the value that results from replacing any
occurrences of the second parameter (char) found
in the first parameter (char) with the contents of
the third parameter (char).
For example, to replace the name Bob with the
name Robert, enter:
REPLACE ($Submitter$, "Bob",
"Robert").
To replace all occurrences of the double-quote
character (") within a character string with another
character, for example, replacing any instance of a
double quote with the name Robert, enter:
REPLACE ($Submitter$, """", "Robert").
As a result, anywhere a double quote is found in the
Submitter field, the double quote will be replaced
with the name Robert.
RIGHT
(char,int)
char
For single-byte languages. Returns the right-most
bytes of the first parameter (char) up to the
number of bytes indicated by the second parameter
(int).
For example, to set the value of a field to the last
four bytes of an account code, enter:
RIGHT($Account#$,4).
Assigning values using function results 231
BMC Remedy Action Request System 7.0
Function
Arguments
Return
Description
RIGHTC
(char,int)
char
For single-byte or multi-byte languages. Returns
the right-most characters of the first parameter
(char) up to the number of characters indicated by
the second parameter (int).
For example, to set the value of a field to the last
four characters of an account code, enter:
RIGHTC($Account#$,4).
ROUND
(real) or
(decimal)
int
Returns the rounded value of a real number. For
example, 5.1 to 5.4 are rounded to 5, and 5.5 to 5.9
are rounded to 6.
RPAD
(char,int,char)
char
For single-byte languages. Returns the value that
results from padding the first parameter (char) on
the right with the value of the third parameter
(char) so that the resulting value is the length (in
bytes) of the second parameter (int) or the length
of the original string, whichever is longer.
For example, enter RPAD($Submitter$,20," ")
to add blank spaces after a submitter’s name to
make the entry 20 bytes long.
RPADC
(char,int,char)
char
For single-byte or multi-byte languages. Returns
the value that results from padding the first
parameter (char) on the right with the value of the
third parameter (char) so that the resulting value is
the length (in characters) of the second parameter
(int) or the length of the original string, whichever
is longer.
For example, enter
RPADC($Submitter$,20," ") to add blank
spaces after a submitter’s name to make the entry
20 characters long.
RTRIM
(char)
char
Returns the value of (char) after deleting any blank
spaces and tabs to the right.
SECOND
(timestamp)
int
Returns the seconds from the time stamp
(0 to 59).
232 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Function
Arguments
Return
Description
STRSTR
(char,char)
int
For single-byte languages. Returns the position (in
bytes) of the second parameter (char) if it is found
in the first parameter (char). If the second string is
not found, returns a –1.
This function is zero-indexed (that is, numbering
of bytes begins at 0).
STRSTRC
(char,char)
int
For single-byte or multi-byte languages. Returns
the position (in characters) of the second
parameter (char) if it is found in the first
parameter (char). If the second string is not found,
returns a –1.
This function is zero-indexed (that is, numbering
of characters begins at 0).
SUBSTR
(char,int [, int])
char
For single-byte languages. Returns the substring of
bytes in the first parameter (char) starting at the
position (in bytes) indicated by the second
parameter (int) and continuing to the position
indicated by the third parameter (int). The string is
zero-indexed (that is, numbering of bytes begins at
0). If the third parameter is not included, the
function returns bytes to the end of the string.
For example, to set the value of a field to six bytes
of the Location field, skipping a three-byte prefix,
enter:
SUBSTR($Location$, 3, 8).
SUBSTRC
(char,int [, int])
char
For single-byte or multi-byte languages. Returns
the substring of characters in the first parameter
(char) starting at the position (in characters)
indicated by the second parameter (int) and
continuing to the position indicated by the third
parameter (int). The string is zero-indexed (that is,
numbering of characters begins at 0). If the third
parameter is not included, the function returns
characters to the end of the string.
For example, to set the value of a field to six
characters of the Location field, skipping a threecharacter prefix, enter:
SUBSTRC($Location$, 3, 8).
TIME
(timestamp)
char
Returns the time portion of the time stamp.
Assigning values using function results 233
BMC Remedy Action Request System 7.0
Function
Arguments
Return
Description
TRUNC
(real) or
(decimal)
int
Returns the truncated value of a real number. For
example, 5.1 through 5.9 are truncated to 5.
UPPER
(char)
char
Returns all characters in the string (char) as
uppercase characters.
Note: No conversion will be performed to double-
byte alphabetic characters.
WEEKDAY
(timestamp)
int
Returns the weekday of the time stamp
(1 to 7, where 1=Sunday and 7=Saturday).
YEAR
(timestamp)
int
Returns the year portion of the time stamp.
Note: When a length (int) is located in the middle of double-byte characters,
the length is treated as (length -1).
Assigning values from process results
You can set a field to the stdout value that results from running a specified
process. The process used to set the field can be located on one of the
following machines:
The client system (active links only)
The server system on which an AR System server has been installed
WARNING: If the process runs on the server, it will use the permissions of the
user who started the AR System server. If the process runs on the client, it
will use the permissions of the user who started BMC Remedy User. This
can have security implications for your system.
The syntax identifies where the process that you want to run is located.
For active links, you can run a process in the following ways:
On the client machine—To access a process located on the same machine
as the client, use the following syntax:
$PROCESS$ <process_to_run>
234 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
On the current AR System server—To use a process located on Server_A
and to set a field located in a form that resides on Server_A, use the
following syntax:
$PROCESS$ @@:<process_to_run>
On any specific AR System server—To use a process located on Server_B
to set a field located in a form that resides on Server_A, use the following
syntax:
$PROCESS$ @Server_B:<process_to_run>
where Server_B is the name of a specific AR System server.
For filters or escalations, the syntax for loading the return of a process is as
follows:
$PROCESS$ <process_to_run>
The $PROCESS$ tag indicates that all text that follows is a command line. The
command line can include substitution parameters from the current screen
to enable values to be placed into the command line before it is executed. You
can enter as many as 255 characters for your command definition. The
command can be as many as 4096 characters after the substitution
parameters are expanded. The actual maximum length is limited by the
operating system in use with AR System. Select substitution parameters (and
the $PROCESS$ string) from the Value list.
For a list of available $PROCESS$ commands, see “Table of Run Process and
$PROCESS$ commands” on page 242.
When the action is executed:
1 The specified command line is executed.
2 The calling program waits for the process to be completed.
3 The program reads and processes all data returned to stdout according to the
exit status code that the process returns.
4 If the process returns an exit status code of 0, the returned data is used as the
value for the field.
The data is expected in text format and is converted, as needed, to match the
data type of the target field. If the process returns a code other than 0, it is
assumed that there was an error and the process failed. In this case, the
returned value is treated as the text of an error message and is returned to the
user.
Assigning values from process results 235
BMC Remedy Action Request System 7.0
If the process is located on a server, activity for that server thread is blocked
until the process is completed or the process interval is exceeded. If the
process has timed out, the server stops its blocking action but does not stop
the process. However, the server ignores any process response after the timeout. You can use the Timeouts tab in the Server Information window to
configure the process interval so that the server continues processing other
tasks, even if the requested process response has not been received. For more
information, see the timeouts and configuration information in the
Configuring guide.
For active links, when you design an active link that loads field values from a
process that is run on the client, be aware of the hardware platforms and
operating systems that your clients might be using. The process that you are
specifying might not be available on all platforms and operating systems. If
your users run the client tools on more than one type of platform or
operating system, you can build a qualification for the active link by using the
$HARDWARE$ and $OS$ keywords to verify that the client is running on an
appropriate platform and operating system at the time the active link
executes. See Chapter 3, “Building qualifications,” for more information.
When assigning values from process results, remember the following tips:
Adjust your command syntax appropriately for the platform on which
your server is running and include the explicit path to the command; for
example, /home/jim/bin/<command>. In a Windows environment, you
also must specify the drive; for example,
d:\home\jim\bin\<command.bat>.
On a Windows server, you can only run a process that runs in a console
(such as a .bat script or runmacro.exe).
In a UNIX environment, the process runs under a Bourne shell.
Use double quotation marks around substituted fields when the values
might contain spaces or other special characters; for example, /bin/cmd
"$<field>$".
Substituted field values that contain hard returns or other special
characters can have unexpected results.
236 Appendix B—Additional ways to use the Set Fields action
Workflow Objects
Assigning values by using arithmetic operators
You can use arithmetic operators to compute a value that you can use in a
Set Fields action. The same arithmetic operators allowed for specifying
qualifications are used to build a computed value (see “Operators” on
page 198). The operation must meet all of the rules for arithmetic operators
and produce a result with a type that is compatible with the target field.
Note: If you include a process result or DDE result (active links only) in a
mathematical operation, the process definition must not be contained
within parentheses and it must be the last item in the operation because all
data after the tag $PROCESS$ or $DDE$ is considered to be part of the
command line or DDE definition.
Some examples of valid arithmetic operators are:
$TIMESTAMP$ - $CREATE-DATE$
$FIRST NAME$ + " " + $LAST NAME$
"hostname = " + $PROCESS$ hostname
Assigning values by using arithmetic operators 237
BMC Remedy Action Request System 7.0
238 Appendix B—Additional ways to use the Set Fields action
Appendix
C
Special Run Process and
$PROCESS$ commands
Through the Run Process workflow action or by using $PROCESS$ in a Set
Fields and Push Fields workflow action, you can run separate processes in
AR System. In general, these actions are used to perform operations in
support of your application.
The following topics are provided:
Overview (page 240)
Run Process and $PROCESS$ syntax (page 240)
Syntax exception—Special commands with qualifications (page 241)
Table of Run Process and $PROCESS$ commands (page 242)
For more information about how the Run Process action works, see the
Integrating with Plug-ins and Third-Party Products guide.
Special Run Process and $PROCESS$ commands 239
BMC Remedy Action Request System 7.0
Overview
Run Process and $PROCESS$ commands look and act like a process from the
perspective of the workflow definition, but they do not actually cause the
system to run a process. Instead, the server “traps” these special process
names and performs the operations directly.
Some commands are available only in the Run Process action, and others are
available only for $PROCESS$ in Set Fields and Push Fields actions. Some are
available in all workflow, and others are available in active links only. Any
action that is identified as being available in filters can be run only from an
active link using the “Run Process on the server” syntax to direct the
command to be run on the server. The commands are really available on the
server, not “to filters.” For more information, see “Assigning values from
process results” on page 234.
Run Process and $PROCESS$ syntax
When using these commands, remember that they are case-sensitive. You
must specify the commands exactly as they are listed, including
capitalization. If incorrect capitalization is used, AR System will attempt to
run an external process with the given name.
All of the commands in this section also follow the characteristics of a process
run from the command line. This means that each parameter needs to be
gathered as a single argument on the command line:
If a parameter includes a space or a special character, you must put
quotation marks around the value. Also surround any keywords with
quotation marks in case the substituted value contains spaces or special
characters.
If a value contains one or more quotation marks, you must double the
quotation marks and put quotation marks around the entire value.
Quotation marks are a special character.
For example, you enter the following values as shown:
Value
Syntax
AR System
“AR System”
AR “System” User
“AR ““System”” User”
$SCHEMA$
“$SCHEMA$”
240 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
Syntax exception—Special commands with
qualifications
Any arguments before the final argument follow the rules described in the
previous section.
These rules do not apply for the final argument of certain commands where
the final argument is a qualification or a substitution string. These
commands include the Application-Parse-xxx, Application-Format-xxx,
and Application-Query-Delete-Entry commands. For the final argument,
no formatting is enforced.
For example, if you run the Application-Query-Delete-Entry command
for the form ABC DEF and the qualification is 'User Name' = "Fred", you
would specify:
Application-Query-Delete-Entry "ABC DEF" 'User Name' = "Fred"
The form name parameter is quoted to keep it as a single argument.
However, for the final argument (the qualification), there are no
surrounding quotation marks, and there are no double quotation marks.
Syntax exception—Special commands with qualifications 241
BMC Remedy Action Request System 7.0
Table of Run Process and $PROCESS$ commands
The following table lists all the available Run Process and $PROCESS$ special
commands in alphabetical order with columns that detail where the
command can be run and its description.
AL1 F/E2 Command and Description
Application-Bus-Time-Add “<StartTime>” [“<Offset>”
[“<OffsetUnits>” [“<HolidayScheduleName>”
[“<WorkdayScheduleName>”[“<BusinessActivityName1>”
“<BusinessActivityName2>”… ]]]]
RP3 $4
Returns a new time that is the requested offset into the future, taking
availability and business hours and holidays into account.
Offset is a value of zero (0) or greater than zero. The default is 1 hour.
Offset unit values are:
1—Seconds
2—Minutes
3—Hours
4—Days
For more information, see the Configuring guide.
Application-Bus-Time-Assoc-Add “<StartTime>” [“<Offset>”
[“<OffsetUnits> [“<HolidayScheduleName>”
[“<WorkdayScheduleName>” [-e "EntityID1" "EntityID2"…
[-a “<BusinessActivityName1>” “<BusinessActivityName2>”…
]]]]]]
The Application-Bus-Time-Assoc-Add command is a more efficient
version of the Application-Bus-Time-Add command.
For more information, see the Configuring guide.
Application-Bus-Time-Assoc-Diff “<StartTime>” “<EndTime>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[-e "EntityID1" "EntityID2"… [-a
“<BusinessActivityName1>” “<BusinessActivityName2>”… ]]]]
The Application-Bus-Time-Assoc-Diff command is a more
efficient version of the Application-Bus-Time-Diff command.
For more information, see the Configuring guide.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
242 Appendix C—Special Run Process and $PROCESS$ commands
Web5
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
Application-Bus-Time-Get-Assoc-Free-Window
“<StartTimeRange>” “<EndTimeRange>” “<Level>”
“<Duration>” “<EarliestStartTime>”“<LatestEndTime>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[-e "EntityID1" "EntityID2"… [-a
“<BusinessActivityName1>” “<BusinessActivityName2>”… ]]]]
Web5
The Application-Bus-Time-Get-Assoc_Free-Window command is a
more efficient version of the Application-Bus-Get-Free-Window
command.
For more information, see the Configuring guide.
Application-Bus-Time-Get-Assoc-Get-Next-Window
“<StartTimeRange>” “<EndTimeRange>” “<Duration>”
“<WindowFlag>” [“<HolidayScheduleName>”
[“<WorkdayScheduleName>” [-e "EntityID1" "EntityID2"…
[-a “<BusinessActivityName1>” “<BusinessActivityName2>”…
]]]]
The Application-Bus-Time-Get-Assoc_Next-Window command is a
more efficient version of the Application-Bus-Get-Next-Window
command.
For more information, see the Configuring guide.
Application-Bus-Time-Assoc-Subtract “<StartTime>”
[<Offset> [<OffsetUnits> [<HolidayScheduleName>
[<WorkdayScheduleName> [-e "EntityID1" "EntityID2"…
[-a “<BusinessActivityName1>”
“<BusinessActivityName2>”...]]]]]]
The Application-Bus-Time-Assoc-Subtract command is a more
efficient version of the Application-Bus-Time-Subtract command.
For more information, see the Configuring guide.
Application-Bus-Time-Diff “<StartTime>” “<EndTime>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[“<BusinessActivityName1>” “<BusinessActivityName2>”… ]]]
Returns an integer that represents the number of seconds between the
start and stop time, taking business hours into account.
For more information, see the Configuring guide.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 243
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
Application-Bus-Time-Get-Free-Window “<StartTimeRange>”
“<EndTimeRange>”“<Level>” “<Duration>”
“<EarliestStartTime>”“<LatestEndTime>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[“<BusinessActivityName1>” “<BusinessActivityName2>”… ]]]
RP3 $4
Returns the start of the next time available or unavailable time segment at
the same level or a higher level that is duration seconds long. If duration
is zero, it returns the next time segment.
For more information, see the Configuring guide.
Application-Bus-Time-Get-Next-Window “<StartTimeRange>”
“<EndTimeRange>” “<Duration>” “<WindowFlag>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[“<BusinessActivityName1>” “<BusinessActivityName2>”… ]]]
Returns the start of the next time available or unavailable time segment
that is duration seconds long. If duration is zero, it returns the next
time segment.
For more information, see the Configuring guide.
Application-Bus-Time-Get-Priority-Fit “<StartTime>”
“<EndTime>” “<Priority>” “<Duration>” “<ScheduleTime>”
[“<HolidayScheduleName>” [“<WorkdayScheduleName>”
[“<BusinessActivityName1>” “<BusinessActivityName2>”…
]]]]
Returns the time where a schedule that is <Duration> seconds long fits.
It uses <Priority> to determines a time period where no conflicting
schedules of higher priority exist.
For more information, see the Configuring guide.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
244 Appendix C—Special Run Process and $PROCESS$ commands
Web5
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
Application-Bus-Time-Subtract “<StartTime>” [<Offset>
[<OffsetUnits> [<HolidayScheduleName>
[<WorkdayScheduleName> [<BusinessActivityName1>
[<BusinessActivityName2>]]]]]]
Web5
Returns a new time that is the requested offset into the past, taking
business hours into account.
Offset is a value of zero (0) or greater than zero. The default is 1 hour.
Offset unit values are:
1—Seconds
2—Minutes
3—Hours
4—Days
For more information, see the Configuring guide.
Application-Confirm-Group <group_ID>
Validates if the current user is a member of the specified group. Returns
one of the following integers:
1—Indicates that the user is a member of the group.
0—Indicates that the user is not a member of the group, or that the
group ID specified does not correspond to a valid group.
This command is not context sensitive for a given entry. Validation of
group IDs 0, 3, 4, or 7 will return 1.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 245
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
RP3 $4
Application-Confirm-Password <password>
Validates if the password is the password for the current user. For
<password>, you can use a reference to field 102, which is the password
field. Returns one of the following integers:
1—Indicates a successful password confirmation.
0—Indicates that the password is not valid.
If you used AR System version prior to 6.0 to create workflow involving a
Password field (ID 102), the workflow might not function in AR System
versions 6.0 and later. Version 6.0 included enhanced encryption and
tighter security controls. To work around this issue, use the
Application-Confirm-Password $PROCESS$ command. For more
information about the Password field, see the Form and Application
Objects guide.
The Application-Confirm-Password command will work only if you
set your workflow to execute on the server side by prepending two
@characters, for example:
@@:Application-Confirm-Password <field ID>
Application-Copy-Field-Value <target_field_ID>
<source_field_ID>
Copies a field on the current form to another field on the current form.
Returns one of the following integers:
1—Indicates that the assignment failed.
0—Indicates that the assignment occurred.
Application-Delete-Entry <form_name> <entry_ID>
Deletes the specified entry.
For example, to delete the entry on the current form with the entry ID
found in the core field 1 (Request ID), enter:
Application-Delete-Entry "$SCHEMA$"
1
2
3
$1$
4
AL = Active Links F/E = Filters and Escalations RP = Run Process $ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
246 Appendix C—Special Run Process and $PROCESS$ commands
Web5
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
Application-Event <event_number>
Web5
Initiates a server event. Event numbers are:
1—Read the configuration file into ARServer memory.
2—Read the group information and definitions from database into
ARServer memory.
3—Read the license file into ARServer memory.
6—Read the user information and definitions from database into
ARServer memory.
For more information about server events and the Server Events form, see
the Developing AR System Applications: Advanced guide.
Application-Format-Qual <form> <VUI> <internal_qualifier>
Converts an internal representation of a qualifier into a qualification
string from the indicated VUI, where <VUI> is the view label.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Format-Qual-Filter <form>
<internal_qualifier>
Converts an internal representation of a qualifier from a filter Run If into
a qualification string.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Format-Qual-ID <form> <internal_qualifier>
Converts an internal representation of a qualifier into a qualification
string using ID format.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Format-Qual-L <form> <internal_qualifier>
Converts an internal representation of a qualifier into a qualification
string using labels.
See “Syntax exception—Special commands with qualifications” on
page 241.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 247
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
Application-Format-Qual-SField <form1> <form2>
<internal_qualifier>
RP3 $4
Converts an internal representation of a qualifier from a Set Fields or
Push Fields filter action into a qualification string.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Format-Val-SField <form1> <field> <form2>
<internal_assignment>
Converts an internal representation of a Set Fields or Push Fields
assignment into an assignment statement.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Generate-GUID [<GUID prefix>]
Generates a globally unique identifier (GUID). The prefix can be a
maximum of two characters, which can contain non-alpha characters
(although alpha characters are recommended). If you do not include the
GUID prefix, it defaults to ID.
Application-Get-Form-Alias <form> [<VUI>]
Retrieves the appropriate form alias for the specified form and VUI. If you
do not include a VUI, the default VUI is used.
Application-Get-Form-Name <form_alias> [<VUI>]
Retrieves the form name for the specified form alias and VUI. If you do
not include a VUI, the default VUI is used.
Application-Get-Next-Recurrence-Time “<FormName>”
“<StartTime>” “<RecurrenceDefinitionName>”
Returns a timestamp representing the recurrence time.
For more information, see the Configuring guide.
Application-Map-Ids-To-Names <form> <string>
Maps the IDs of the fields or keywords in the string to a name
representation.
Application-Map-Ids-To-Names-L <form> <VUI> <string>
For the indicated VUI, maps the IDs of the fields or keywords in the string
to a name representation using labels. If the field label is blank, the
database name will be used.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
248 Appendix C—Special Run Process and $PROCESS$ commands
Web5
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
Application-Map-Names-To-Ids <form> <string>
Maps the names of the fields or keywords in the string to an internal ID
representation.
Application-Map-Names-To-Ids-L <form> <VUI>
<qualification_string>
Web5
For the indicated VUI, maps the labels of the fields or keywords in the
string to an internal ID representation.
For example, to map the IDs in the given string to names using labels
where appropriate, enter:
Application-Map-Ids-To-Names-L "My Form" "" $536870913$
An empty string for the VUI denotes the default VUI for the form.
Application-Parse-Qual <form> <qualification_string>
Converts a qualification string into an internal representation.
For example, to parse the qualification string into its internal
representation, enter:
Application-Parse-Qual "My Form" Integer Field = 99
The qualification string does not need double quotation marks around it
because all data after the form name is treated as the qualification string.
Application-Parse-Qual-Filter <form>
<qualification_string>
Converts a Run If filter qualification string into an internal
representation.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Parse-Qual-L <form> <VUI>
<qualification_string>
For the indicated VUI, converts a qualification string with labels into an
internal representation.
See “Syntax exception—Special commands with qualifications” on
page 241.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 249
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
RP3 $4
Application-Parse-Qual-SField <form1> <form2>
<qualification_string>
Web5
Converts a Set Fields or Push Fields filter qualification string into an
internal representation.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Parse-Val-SField <form1> <field> <form2>
<assignment_statement>
Converts a Set Fields or Push Fields filter assignment statement into an
internal representation.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Query-Delete-Entry <form>
<qualification_string>
Deletes all entries matching the specified qualification.
See “Syntax exception—Special commands with qualifications” on
page 241.
Application-Release-Pending
Causes database operations caused by the current workflow to be sent to
the database immediately.
Note: Use this advanced feature with caution. The command allows
*
workflow to see the results of previous workflow by causing the
previous workflow’s actions to be entered into the database. Using this
command, for example, would cause the results of a Push Fields phase
2 action to be made visible to a Set Fields phase 1 action. However, if
there is a failure after the application command is performed, the entire
transaction including the Push Fields operation is rolled back,
maintaining transactional integrity.
GET-CHANGE-FLAG
Gets the change flag status of the current window. 1 means that changes
were made, and 0 means that no changes were made.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
250 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
PERFORM-ACTION-ACTIVE-LINK
Web5
Executes all active links associated with the specified Execute On
condition (and field ID, as appropriate). The active links fire as if the
Execute On condition indicated occurred. For example,
PERFORM-ACTION-ACTIVE-LINK 8 specifies to run all On Modify active
links as if a modify operation was performed. The active links fire, but no
modify is actually performed.
The options for this command are as follows:
Button: PERFORM-ACTION-ACTIVE-LINK 1 <field_ID>
Return/Table Dbl-Clk: PERFORM-ACTION-ACTIVE-LINK 2
<field_ID>
1
Submit: PERFORM-ACTION-ACTIVE-LINK 4
Modify: PERFORM-ACTION-ACTIVE-LINK 8
Display: PERFORM-ACTION-ACTIVE-LINK 16
Menu Choice: PERFORM-ACTION-ACTIVE-LINK 128 <field_ID>
Lose Focus: PERFORM-ACTION-ACTIVE-LINK 256 <field_ID>
Set Default: PERFORM-ACTION-ACTIVE-LINK 512
Search: PERFORM-ACTION-ACTIVE-LINK 1024
After Modify: PERFORM-ACTION-ACTIVE-LINK 2048
After Submit: PERFORM-ACTION-ACTIVE-LINK 4096
Gain Focus: PERFORM-ACTION-ACTIVE-LINK 8192 <field_ID>
Window Open: PERFORM-ACTION-ACTIVE-LINK 16384
Un-Display: PERFORM-ACTION-ACTIVE-LINK 65536
Window Close: PERFORM-ACTION-ACTIVE-LINK 32768
Copy To New: PERFORM-ACTION-ACTIVE-LINK 131072
Window Loaded: PERFORM-ACTION-ACTIVE-LINK 262144
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 251
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
* PERFORM-ACTION-ADD-ATTACHMENT <field_ID> [<file_name>]
RP3 $4
Web5
Adds an attachment to an attachment field, and returns a value of 0
(Successful). If the attachment is not added, you will receive one of the
following codes:
* 1: Cancelled
2: Failed
For filters and escalations, the field ID must be an attachment field, and
the file name is required.
For active links:
The file name is optional. If omitted, a Browse dialog box is displayed
to allow you to select a file name. (For forms views on the web, a Browse
dialog box is always displayed.)
The field ID can be an attachment field or an attachment pool. If the
field ID specified is an attachment field, the attachment is added to the
specified field. If the field has a value, the existing value is overwritten.
If the field ID is an attachment pool, the attachment is added to the first
available field within the pool that has no attachment. If there is no
attachment meeting this criteria within the pool, no action is taken.
PERFORM-ACTION-APPLY
Performs the Apply or Save operation on the current window. For Search
windows, the search is performed.
PERFORM-ACTION-DELETE-ATTACHMENT <field_ID>
Deletes an attachment from an attachment field, and returns a value of 0
(Successful). If the attachment is not deleted, you will receive one of the
following codes:
*
1
1: Cancelled
2: Failed
PERFORM-ACTION-EXIT-APP
Exits the Windows client, or logs out of the web client.
PERFORM-ACTION-GET-FIELD-LABEL <field_ID>
Returns a field label. Use this command in a Set Fields action with
$PROCESS$ to obtain the return value.
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
252 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
AL1 F/E2 Command and Description
*
RP3 $4
Web5
PERFORM-ACTION-GET-PREFERENCE <field_ID>
[<-optional_preference_name>]
Gets the value of the field you specify from the User Preferences form. If
the field contains a list of values, then it gets the value for
<optional_preference_name>.
For example, to get the value of the User Locale field, enter the following
command:
PERFORM-ACTION-GET-PREFERENCE 20121
where 20121 is the field ID of the User Locale field.
To find the field ID:
1 Open the AR System User Preferences form using BMC Remedy
*
Administrator.
2 Double-click the field in question to display the Field Properties dialog
box.
3 Click the Database tab. The field ID is displayed in the ID field.
PERFORM-ACTION-GO-HOME
Opens the form configured as your Home Page.
PERFORM-ACTION-HOME-FIELD-REFRESH
Refreshes the Application List field on the Home Page form. Typically,
you would use this command to display a subset of entry points based
upon the values that are dynamically entered into the reserved character
field ID 1576.
PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM
<NavBarItemID>
Set focus to the specified navigation bar item.
PERFORM-ACTION-NEXT
Moves to the next request in the Results pane and displays the details in
the Details pane.
PERFORM-ACTION-OPEN-ATTACHMENT <field_ID>
Opens an attachment from an attachment field, and returns a value of 0
(Successful). If the attachment is not opened, you will receive one of the
following codes:
1: Cancelled
2: Failed
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 253
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
PERFORM-ACTION-OPEN-URL [<current or new>]<URL_string>
RP3 $4
Web5
Opens the specified URL in a browser. For the Windows client, a browser
is opened. For the web client, the URL is opened as follows:
To open the page in a new browser window, enter:
PERFORM-ACTION-OPEN-URL <URL_string>
or
PERFORM-ACTION-OPEN-URL new <URL_string>
To open the page in the current browser window, enter:
PERFORM-ACTION-OPEN-URL current <URL_string>
PERFORM-ACTION-PREV
Moves to the previous request in the Results pane and displays the details
in the Details pane.
PERFORM-ACTION-REFRESH-PREFERENCE <flag>
Refreshes the preferences for BMC Remedy User. The flag options are:
* 1—Saves all modified preferences from BMC Remedy User to the
preference server, and then reloads from the preference server.
0—Discards all modified preferences in BMC Remedy User and
reloads from the preference server.
PERFORM-ACTION-SAVE-ATTACHMENT <field_ID> [<file_name>]
Saves an attachment from an attachment field to a file, and returns a value
of 0 (Successful). If the attachment is not saved, you will receive one of the
following codes:
1: Cancelled
2: Failed
For filters and escalations, the file is saved on the server machine. The field
ID must be an attachment field, and the file name is required.
For active links, the file is saved on the client machine. The field ID can be
an attachment field or an attachment pool. If you specify an attachment
pool for the field ID, the first available attachment is saved. The file name
is optional. If omitted, a Browse dialog box is displayed to allow you to
select a file name. (For forms views on the web, a Browse dialog box is
always displayed.)
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
254 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
PERFORM-ACTION-SEND-EVENT <target> <event_type>
<event_data>
Web5
Sends an event to another window.
<target> is the window to which to send the event. Possible values are:
@—The “at” sign signifies the parent of the current window.
#—The number sign character signifies all child windows of the current
window.
*—The asterisk character signifies all windows managed by the client
environment, even the current window.
<event_type>—The name of the event. This is an arbitrary string
defined by the application author (for example, ChildClosed). The
receiving workflow can access the value of <event_type> through the
EVENTTYPE keyword.
<event_data>—The data for the event.
F<datavisualizatopm_module_fieldID>—The target for sending
events is the module field in the current form.
For more information, see “Sending events between windows” on
page 262 and “Sending events to the Data Visualization definitions” on
page 259.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 255
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
PERFORM-ACTION-SET-PREFERENCE <field_ID> <value>
RP3 $4
Web5
Sets the value of the field you specify in the User Preferences form. For
example, to set the value of the User Locale field to Japanese, enter the
following command:
PERFORM-ACTION-SET-PREFERENCE 20121 ja_JP
where 20121 is the field ID of the User Locale field and ja_JP is the value
that represents a Japanese locale.
To find the field ID:
1 Open the AR System User Preference form using BMC Remedy
Administrator.
2 Double-click the field in question to display the Field Properties dialog
box.
3 Click the Database tab. The field ID is displayed in the ID field.
To find the value or format of a user preference field:
1 Log in to a preference server using BMC Remedy User.
2 Choose Tools > Options. The Options window is displayed.
3 Specify a value for a user preference, and click OK.
4 Open the AR System User Preference form to see what format is used
or what value is stored in the corresponding field. This is the format or
value you specify for the value argument.
PERFORM-ACTION-TABLE-CLEAR <table_field_ID>
Clears the contents of the table field.
For list view table fields, tree view table fields, and alert list fields, returns
the table to its initial state.
For results list fields, fires workflow and then resets the mode to Query.
This is equivalent to pressing the New Search form action button.
PERFORM-ACTION-TABLE-CLEAR-ROWCHANGED <table_field_ID>
Clears the ROWCHANGED flag for the current row.
This command is ignored for tree view table fields.
PERFORM-ACTION-TABLE-DESELECTALL <table_field_ID>
Deselects all entries in a table field. This command is valid for all types of
table fields.
1
AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
256 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
AL1 F/E2 Command and Description
RP3 $4
Web5
PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN <field_ID>
[<return_type>]
Returns the field ID or level of the selected node, which starts at 1. If root
is selected, the command returns 0. If nothing is selected, the command
returns NULL. The arguments for this command are:
Field ID—The field ID of the tree field.
Return type—1 returns the selected column’s field ID. Anything other
than 1 returns the number of the level.
To return the field ID of a tree with an ID of 536870913, enter the
following command:
PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN 536870913 1
To return the level of a tree with an ID of 536870913, enter the following
command:
PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN 536870913
The PERFORM-ACTION-TABLE-GET-SELECTED-COLUMN command
works only with tree view table fields.
PERFORM-ACTION-TABLE-IS-LEAF-SELECTED <table_field_ID>
Returns 1 if selected node is a leaf, and returns 0 if the selected node is not
a leaf or if nothing is selected.
PERFORM-ACTION-TABLE-NEXT-CHUNK <table_field_ID>
Displays the next chunk of data in a table.
If the action is for a results list, use reserved field ID 1020.
PERFORM-ACTION-TABLE-PREV-CHUNK <table_field_ID>
Displays the next chunk of data in a table.
If the action is for a results list, use reserved field ID 1020.
This command is ignored for tree view table fields.
PERFORM-ACTION-TABLE-REFRESH <table_field_ID>
[<start_row>] [<number to retrieve>]
Refreshes a table. You can optionally specify a start row and a maximum
number of rows to retrieve.
If the action is for a results list, use reserved field ID 1020.
This command is valid for all types of table fields.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
Table of Run Process and $PROCESS$ commands 257
BMC Remedy Action Request System 7.0
AL1 F/E2 Command and Description
PERFORM-ACTION-TABLE-REPORT <table_field_ID>
RP3 $4
Web5
Runs a report on the selected rows in a table. If no rows are selected, the
report is on the entire table.
This command is ignored for tree view table fields.
PERFORM-ACTION-TABLE-SELECT-NODE <field_ID> <row_number>
[<column_number>] [<flag>]
Selects the specified node in a tree view table. The arguments for this
command are:
Field ID—The field ID of the tree field.
Row number—The 1-based row position of the node.
Column number (optional)—The column (level) of the node. If you
enter an invalid column number, a leaf is selected.
Flag—1 expands the selected node. Anything other than 1 is ignored.
An example use of the command is:
PERFORM-ACTION-TABLE-SELECT-NODE 536870913 3 4 1
This command would select a node whose tree field ID is 536870913, and
the node is in row 3 and column 4. The command would also request that
the node will be expanded.
PERFORM-ACTION-TABLE-SELECTALL <table_field_ID>
Selects all the entries in a table field. This command is valid for all types
of table fields.
For a tree view table field, the command selects the root label, which
represents all data. If there is no root label, the command selects nothing.
SET-CHANGE-FLAG <1 or 0>
Sets the change flag status of the current window to on (1) or off (0).
SET-RO-COLOR <red code>,<green code>,<blue code>
Sets the background color of read-only fields according to red, green, blue
(RGB) color coding. For example, an RGB code for blue is 0,0,255.
1 AL = Active Links 2F/E = Filters and Escalations 3RP = Run Process 4$ = $PROCESS$ 5Web = Supported by web clients
* Valid only when used with a Set Fields action.
258 Appendix C—Special Run Process and $PROCESS$ commands
Workflow Objects
Sending events to the Data Visualization definitions
To send an event to a Data Visualization field
1 Create a form with a Data Visualization field.
2 Choose the module to display in the field.
3 Add the following active link action to send an event type and event data to
the module field.
PERFORM-ACTION-SEND-EVENT F<data visualization fieldID>
<eventtype> [<eventdata>]
For example:
PERFORM-ACTION-SEND-EVENT F536870914 "DisplayItem" $ItemName$
Where:
536870914 is the data visualization field ID.
DisplayItem is an event type that is recognized by the module.
$ItemName$ is a field on the form that contains the name of the item to
be displayed in the module field.
Sending events to the Data Visualization definitions 259
BMC Remedy Action Request System 7.0
260 Appendix C—Special Run Process and $PROCESS$ commands
Appendix
D
Workflow extras
This section describes additional workflow capabilities you can use in
AR System. The following topics are provided:
Sending events between windows (page 262)
Using workflow to “walk” a table field (page 268)
Workflow extras 261
BMC Remedy Action Request System 7.0
Sending events between windows
You can use active link workflow to send messages to one or more windows.
The ability to send events between windows allows, for example, a child
window to tell a parent window to execute certain active links. Here the
parent window needs to know when some action has happened on the child
window (for example, it is closed) so that workflow on the parent window
can refresh related data. The Send Event functionality provides a way for
windows to synchronize their data, and a mechanism for a parent window to
be notified when a child window has been closed.
To send events between windows, you coordinate the following mechanisms
in BMC Remedy Administrator:
ThePERFORM-ACTION-SEND-EVENT<target><eventtype><event_data>Run
Process command identifies the window to which to send the event. (For
more information, see page 255.)
On Event active link execute condition. (For more information, see
“Defining workflow basics” on page 26.)
Keywords to identify the current event ($EVENTTYPE$), the current event
data ($EVENTDATA$), the current window ($CURRENTWINID$), the window that
sent the event ($EVENTSRCWINID$), and the last opened window
($LASTOPENEDWINID$). (For more information, see “Keywords” on
page 203.)
Note: On the web, opening windows from workflow is not synchronous. For
example, if an active link contains an Open Window action and the next
action is a send event Run Process action, the child window will not
receive the event. (The active link will work correctly in BMC Remedy
User.) To solve this issue on the web, set up the workflow so that the
parent or child window is loaded, and then the send event action is
executed.
262 Appendix D—Workflow extras
Workflow Objects
Additional considerations for sending events
The <event_type> specified in the PERFORM-ACTION-SEND-EVENT <target>
<event type> <event data> command can be accessed by the active link
running on the Event condition through using the $EVENTTYPE$ keyword.
Event data to be attached can be represented in the $EVENTDATA$ keyword.
Likewise, the window ID of the window sending the event can be accessed by
the recipient using the $EVENTSRCWINID$ keyword.
When using the Run Process send event action with web clients, sending a
message to a parent window or child windows will behave in an undefined
fashion if the contents of the windows are changed by navigating to a new
URL. Navigating to a new URL by going to a new page, by pressing the Back,
Forward, or Reload buttons on your browser, or by using an Open Window
active link action that reloads new data into an existing window will cause the
form to be unloaded and cause this undefined behavior.
If this event is sent to a data visualization field, the <target> must be F<data
visualization field ID>.
An example of Run Process syntax to send the event ChildClosed to the
current window’s parent is PERFORM-ACTION-SEND-EVENT @ ChildClosed; to
send the ParentClosed event to the current window’s children is PERFORMACTION-SEND-EVENT # ParentClosed.
Note: Quotation marks are optional in the Run Process command if the
<event_type> does not contain a space. For example, they are optional for
PERFORM-ACTION-SEND-EVENT @ EventA, but you must use them for
PERFORM-ACTION-SEND-EVENT @ "This is the event".
If you are using field references for the <target> and <event_type>, make
sure the field is set properly prior to executing the Run Process command.
Sending events between windows 263
BMC Remedy Action Request System 7.0
Example of sending events between windows
The following example shows how you can send an event from a child
window to a parent window. When a user modifies a record in the Child
Window form, an After Modify condition in the active link automatically
sends an event to the Parent Window form and updates a table field (as
shown in Figure D-1).
Figure D-1: Sending event from child window to parent window
The following procedure shows how to reproduce the workflow for sending
an event from a child window to a parent window, shown in Figure D-1. The
concepts used here are straightforward, so that you could easily reverse
sending the event from a parent window to a child window.
Note: You cannot have workflow that opens a dialog box and then sends an
event to the dialog box. Dialog boxes are modal, and subsequent send
event actions or active links will not fire until the dialog box closes. In this
case, the dialog box no longer exists. Instead, use an On Loaded active link
condition in the dialog box to send an event to itself, using the keyword
$LASTOPENEDWINID$ as target.
264 Appendix D—Workflow extras
Workflow Objects
To send an event to a parent window
1 Create a form (for example, Parent Window).
2 Create another form (for example, Child Window).
3 Add a table field to the Parent Window form.
4 Open the Field Properties window of the table field, and then click the Table
Property tab.
5 Select Child Window in the Form field.
The columns of the table field in Parent Form must point back to the Child
Window form.
6 Create the following columns in the table field:
Request ID (Column)
Submitter (Column2)
Short Description (Column3)
These columns will help you identify which records in the table field to
modify.
7 Create an active link (Child Send Event to Parent After Modify) with a Run
Process action.
a Configure the Basic tab of the active link:
Form Name: Child Window
Execute On: After Modify
Run If: ‘Submitter’ != ‘Assigned To’
You want the active link in the child window to fire if the submitter and
assignee are not the same user.
b Configure the If Action tab and create the Run Process action that sends
the event:
Action: Run Process
Command Line: PERFORM-ACTION-SEND-EVENT
@ “RefreshTable”
This Run Process command sends the RefreshTable event to the parent
window. You will use this same event string later in active link workflow to
catch the sent event in the parent window.
Sending events between windows 265
BMC Remedy Action Request System 7.0
Tip: Make sure the target symbols (@, #, *) are used correctly. If you are trying
to send an event to a parent window, do not use #.
You use this Run Process command and its special syntax to send messages
to one or more windows. For example, to send an event to all windows, you
would enterPERFORM-ACTION-SEND-EVENT * “All Windows”. You could also send
events to a specific window:
PERFORM-ACTION-SEND-EVENT
PERFORM-ACTION-SEND-EVENT
PERFORM-ACTION-SEND-EVENT
PERFORM-ACTION-SEND-EVENT
$536870921$ Processing
$Short Description$ “network is down”
$My Field$ “process request”
$LASTOPENEDWINID$ “close now”
This command uses an established mechanism in the client environments to
support special commands that are not run as executables, but as internal
commands within the client. For detailed information about the command
syntax, see page 255.
Note: Events are asynchronous, and the Run Process command will return
immediately. Other windows receive the events and process the workflow
at a later time.
8 Create an active link (Parent Catch Event) with a Change Field action to
catch the sent event.
a Configure the Basic tab of the active link:
Form Name: Parent Window
Execute On: Event
Run If: $EVENTTYPE$
= “RefreshTable”
Because event names are intended to be unique, this active link fires only
if it receives the RefreshTable event.
Note: You must use quotation marks in the Run If qualification for the event
type.
266 Appendix D—Workflow extras
Workflow Objects
You can trigger active links by examining the values of the EVENTSRCWINID,
CURRENTWINID, or EVENTTYPE keywords in the Run If qualification. Here the
EVENTTYPE keyword is used in the Run If qualification to fire the active link
if the parent window catches the RefreshTable event sent by the child
window.
Tip: Use the Keyword menu for entering Send Event keywords to avoid
spelling errors.
b Configure the If Action tab and create the Change Field action that
responds to the sent event:
Action: Change Field
Field Name: Table Field
Refresh Table Field: Yes
Here the rows in the table field are automatically refreshed after changes are
made to the underlying request.
9 Log in to BMC Remedy User, and open the Child Window form.
10 As a test, create several tickets in the Child Window form, but create one
ticket with John as the value of the Submitter and Assigned To fields. Make
sure you fill in the required fields.
11 Open the Parent Window form, and click the table field to refresh it.
12 Double-click the request assigned to John in the Results List to open the
Child Window form.
13 Change the assignee to another name and make changes in the Short
Description field (for example, Catch event in parent window), and then save
the request.
When you modify the request, the active link workflow is triggered and sends
the child window event to the parent window. The table field in the parent
window becomes refreshed automatically with your changes.
If the target window is in the process of executing workflow, that workflow
will complete before the event is received.
Sending events between windows 267
BMC Remedy Action Request System 7.0
Tip: If the active links do not fire in the target window, make sure the event
type string in the Run If qualification matches exactly to the event type
string in the Run Process command.
Using workflow to “walk” a table field
This section describes special workflow you can create to get values in a table
field without having the user interact directly with the table.
Note: The functionality described here was replaced in version 5.1 by the
Table Loop feature in the Call Guide action. For more information, see
“The Call Guide active link or filter action” on page 53.
“Table walk” lets you control whether workflow associated with a row
executes when the row is selected. For example, you can create an active link
that executes when a user clicks a button, and counts the number of rows in
the table that match certain criteria. You can choose whether this active link
also triggers other workflow that normally executes when a user selects a row.
You can use values you get from a “table walk” in other active link actions,
for example, to set or push values. Statistical functions (described in
“Assigning values using function results” on page 222) also allow you to sum,
average, and count items in columns, or find minimum and maximum
values. Because these functions operate directly on the data in the table,
database access time is minimized.
The following table shows the results of placing a table field in the Name field
or the Value field in the Fields section of the Set Fields active link action:
Name Field
Value field
Table field
The row equivalent to the integer is
Integer, or field
selected. See the next table for the specific
containing an
integer. The first row ways to set this.
of table = 1
Table field
268 Appendix D—Workflow extras
Result
The number (where the first row = 1) of
the selected row is returned. For example,
if row 5 is selected, 5 is returned.
Workflow Objects
If you put the table field in the Name field, you must then set the conditions
in the Value field. You determine if the user sees the row highlighted or not,
and if the active link executes or not.
Value field contents
Result
n
Selects and highlights row n and executes
the active link.
The user sees the row highlighted.
-n
Selects and highlights row n and does not
execute the active link.
The user sees the row highlighted.
n + 100000000
Selects row n and executes the active link.
The user does not see the row highlighted.
If a row is selected and is already
highlighted, the highlighting does not
move.
-(n + 100000000)
Selects row n and does not execute the
active link.
The user does not see the row highlighted.
If a row is selected and is already
highlighted, the highlighting does not
move.
Figure D-2 shows an active link that uses a Set Fields action to select a row in
Table Field based on the value in Row Number. This action does not
highlight the row and it does not execute the active link associated with the
row.
Using workflow to “walk” a table field 269
BMC Remedy Action Request System 7.0
Figure D-2: Set Fields action that selects a row without highlighting or executing
To “walk” all rows in a table, create an active link guide that selects a row,
executes workflow or performs other tasks, then increments to the next row,
and so on. For more information about guides, see Chapter 5, “Defining
guides and guide actions.”
270 Appendix D—Workflow extras
Workflow Objects
Figure D-3: Active link guide that “walks” a table field
Using workflow to “walk” a table field 271
BMC Remedy Action Request System 7.0
272 Appendix D—Workflow extras
Index
Symbols
! 198
- 200
!= 201
" 200
% 200
&& 198
* 200
+ 200
/ 200
= 201
>, >= 200
|| 198
A
accelerator keys 172
actions
See also workflow actions
Else 21, 46
If 21, 46
number of actions on If and Else tabs 46
active link actions
Call Guide 51, 53, 138
Change Field 51, 54
Close Dialog 61
Close Window 51, 61
Commit Changes 51, 62
DDE 51, 63
Direct SQL 51, 64, 66, 144
Exit Guide 51, 66, 144
Go To Guide Label 52, 66, 145
active link actions (continued)
Goto 52, 66
Message 51, 52, 69
OLE Automation 52, 78
Open Dialog 78
Open Window 52, 78
Push Fields 53, 97
Run Macro 53, 106
Run Process 53, 108
Set Fields 53, 112
Wait 53, 124, 146
active link actions, using
changing order 50
creating 48
deleting 50
modifying 49
types 51
active link conditions
After Modify 29
After Submit 28
Button/Menu Item 31
Copy to New 29
Display 28, 183
Event 30
Gain Focus 31
guides interacting with 150
Interval 31
Lose Focus 31
Menu/row Choice 30
Modify 28
Return 30
BMC Software Inc., Confidential
Index 273
BMC Remedy Action Request System 7.0
active link conditions (continued)
Search 29
Set Default 29
Submit 28
Un-Display 28
Window Close 29
Window Loaded 30
Window Open 29, 183
active link guides 148
active links defined in 133
defining 130
overview 148
active link menu items
permissions 176
properties 171
active link permissions enforced in guides 134
active links
See also active link actions; active link actions,
using; active link conditions; active link
menu items
buttons 176
conditions 25
defining in a guide 133
disabling 27
enabling 27
execution conditions 182
execution order 27
guides interacting with 150
menu items 176
naming 26
overview 14
permissions 21, 134
permissions enforced in guides 134
processing 182
qualifications 32
selecting, for a guide 133
sending events 262
toolbar button 169
trace modes 196
add operator 200
adding
actions 49
menu items 172
menus 172
separators 172
274 Index
advanced
Change Field action 58
Open Window action 94
Push Fields action 101
Set Fields action 120, 121
advanced workflow, Call Guide action 141
After Modify active link condition 29
After Submit active link condition 28
alert notification mechanism 75
AND operator 198
ANSI SQL standards, using 64, 214
APPLICATION keyword 203
ARERR 71
arerror.log file 68, 196
arescl.log file 196
arguments with comma as decimal separator,
specifying 223
arithmetic operators 200
ARNOTE 70
ARNotification (field order in notifications) 78
ARWARN 70
B
Basic properties, workflow 21, 25
Basic settings, guides 130
BMC Remedy Alert 75
BROWSER keyword 203
building qualifications 34
bulk updates 205
button fields
See also toolbar buttons
active links 176
deleting 178
show close 81
Button/Menu Item active link condition 31
C
Call Guide action 138
advanced 141
dynamic fields 141
overview 51, 53
restricted list 140
Change Field action
advanced functionality, defining 58
defining 54
BMC Software Inc., Confidential
Workflow Objects
Change Field action (continued)
dynamic fields, setting 58
overview 51
change history
guides 135
changing
field label 57
label color 58
order of menu items 175
order of toolbar buttons 176
workflow action order 50
CLIENT-TYPE keyword 203
close all (edit menu bar) 173
close all, guides on exit 145
Close Dialog action 61
Close Window action 51, 61
COLAVG function 224
COLCOUNT function 224
COLMAX function 224
COLMIN function 224
color label, changing 58
COLSUM function 225
command line
field tips 111
run process 110
syntax guidelines 111
commands
$PROCESS$ 240
Run Process 240
Commit Changes action 51, 62
conditions
active links 25, 182
escalations 25
filters 25, 184
Continue button label (Wait action) 147
conventions for qualifications 35
Copy To New active link condition 29
creating
filter guides that loop through server-side table
fields 164
guides 128
requests (push fields) 99
cross-reference mechanism in notifications 76
CURRCONVERT function 225
current
action 49
screen (active links) 115
transaction (filters and escalations) 115
CURRENTWINID keyword 203
CURRSETDATE function 225
CURRSETTYPE function 226
CURRSETVALUE function 226
D
data, converting in server-side table fields 167
database
security 219
values, checking 36, 40
DATABASE keyword 203
DATE function 226
DATE keyword 204
DATEADD function 227
DATEDIFF function 227
DATENAME function 227
DATENUM function 228
DAY function 228
days of month (escalations) 125
DDE 51, 63
debug modes, using log files 135, 196
DECRYPT function 228
DEFAULT keyword 204
Delete filter condition 31
Delete menu item (edit menu bar) 173
deleting
actions 50
buttons 178
guides 135
menus 178
deployable applications 22
dialog boxes
buttons, creating 62
closing 61
modal 78
opening 78
writing data back to parent form 62
Direct SQL
action 51, 64, 66, 144
ANSI SQL standards, using 64
assigning values 214
BMC Software Inc., Confidential
Index 275
BMC Remedy Action Request System 7.0
disabling workflow objects 27
Display active link condition 183
displaying
active link condition 28
any match error (push fields) 100
no match error (push fields) 99
divide operator 200
dynamic data exchange. See DDE action
dynamic fields
Call Guide action 141
Change Field action 58
Open Window action 94
Push Fields action 101
Set Fields action 120
E
Else and If actions 21, 46
email
notifications 75
Subject line 77
enabling
menu bar 173
workflow objects 27
ENCRYPT function 228
entry points 127
equal operator 201
error handling 195
errors, message actions 69, 71
escalation actions
changing order 50
creating 48
deleting 50
Direct SQL 51, 64, 66, 144
Log to File 52, 68
modifying 49
Notify 52, 72
Push Fields 53, 97
Run Process 53, 108
Set Fields 53, 112
types 51
Wait 53, 124, 146
escalations
arescl.log 196
conditions 25
disabling 27
276 Index
escalations (continued)
enabling 27
execution order 27
logging activity 196
naming 26
overview 15
performance 124
performance impact of unqualified Run If
statements 32
qualifications 32
time 124
trace modes 196
Event active link condition 30, 262
EVENTSRCWINID keyword 204
EVENTTYPE keyword 204
examples
filter processing 187
filter qualifications 41
guides, creating interactive 156
sending events 264
shared guides 137
shared workflow 24
execution conditions
Interval (escalations) 124
Time (escalations) 124
execution order
active links and filters 27, 183
Goto action 67
Exit Guide action 51, 66, 144
expressions. See qualifications
extension, views and 80, 83, 86, 90
EXTERNAL () operator 199
F
field labels, changing 57
field mapping mode (Open Dialog action) 81
field values, assigning from
another field 115
arithmetic operations 237
different request 118
direct SQL commands 214
function results 222
process results 234
field with execution order (Goto actions) 67
FIELDHELP keyword 204
BMC Software Inc., Confidential
Workflow Objects
FIELDID keyword 204
FIELDLABEL keyword 204
FIELDNAME keyword 204
fields
characteristics in an active link 54
collapse tree, active links 57
expand tree, active links 57
font change, active links 56
hidden, active links 56
including in notifications 77
qualifications 35
shared workflow 23
table, walking 268
visible, active links 56
files
arescl.log 196
name (Log to File action) 69
filter actions
Direct SQL 51, 64, 66, 144
Goto 52, 66
Log to File 52, 68
Message 52, 69
Notify 52, 72
Push Fields 53, 97
Run Process 53, 108
Set Fields 53, 112
Wait 53, 124, 146
filter actions, using
changing order 50
creating 48
deleting 50
modifying 49
types 51
Filter API 219
filter conditions
Delete 31
Get Entry 31
Merge 31
Modify 31
overview 25
Submit 31
filter guides 161
basics, defining 130
filters defined in 133
filter guides (continued)
in server-side table fields 163
looping through table fields 163
filters
See also filter actions; filter actions, using; filter
conditions
defining in a guide 133
enabling 27
execution order 27, 184
how AR System processes 186
logging activity 196
naming 26
overriding phasing 192
overriding, releasing pending operations 193
overriding, special naming convention 193
overview 15
phase 1 actions 185
phase 2 actions 186
phase 3 actions 186
phases 185
phasing exceptions 191
processing 184
processing example 187
qualifications 32, 34
releasing pending operations for phasing
override 193
special naming convention for phasing
override 193
subject line 77
trace modes 196
formatting qualifications 35
forms, selecting for guide 131
functions
arguments with comma as decimal separator,
specifying 223
COLAVG 224
COLCOUNT 224
COLMAX 224
COLMIN 224
COLSUM 225
CURRCONVERT 225
CURRSETDATE 225
CURRSETTYPE 226
CURRSETVALUE 226
DATE 226
BMC Software Inc., Confidential
Index 277
BMC Remedy Action Request System 7.0
functions (continued)
DATEADD 227
DATEDIFF 227
DATENAME 227
DATENUM 228
DAY 228
DECRYPT 228
ENCRYPT 228
HOUR 229
LEFT 229
LEFTC 229
LENGTH 229
LENGTHC 229
LOWER 229
LPAD 229
LPADC 230
LTRIM 230
MAX 230
MIN 230
MINUTE 230
MONTH 230
REPLACE 231
RIGHT 231
RIGHTC 231
ROUND 231
RPAD 232
RPADC 232
RTRIM 232
SECOND 232
set fields operation, using in 222
STRSTR 232
STRSTRC 232
SUBSTR 233
SUBSTRC 233
TIME 233
TRUNC 233
UPPER 222, 233
WEEKDAY 233
YEAR 233
G
Gain Focus active link condition 31
Get Entry filter condition 31
Go To Guide Label action 52, 66, 145
Goto action 52, 66
278 Index
greater than (or equal to) operators 200
GROUPIDS keyword 204
GROUPS keyword 204
guide actions
advanced call guide, defining 141
call guide 138
exit guide 144
go to guide label 145
wait 146
GUIDE keyword 148, 204
guides
active link 148
active links defined in 133
active links, interacting 150
active links, selecting 133
activity, tracing 135
basic, defining 131
Call Guide action 53, 138
change history 135
creating (example) 156
defining 130
defining (overview) 128
deleting 135
execution, controlling 148
exiting 66, 144
filter 161
filters defined in 133
go to label 66, 145
help, creating 135
how active links interact with 150
labels 66, 131, 145
logging activity 135
looping through table fields 153, 163
modifying 135
naming 131
overview 128
Remedy Administrator help text, creating 135
shared 136
shared (examples) 137
specifications 130
trace 135
using 155
Wait action 146
what is a guide? 148
GUIDETEXT keyword 205
BMC Software Inc., Confidential
Workflow Objects
H
handling errors 195
HARDWARE keyword 111, 205, 236
help
guides 135
menus 173
hiding
menu bar 173
hiding menu bar 173
history, status 38
home pages
run process commands 253
home pages, run process commands 253
HOMEURL keyword 205
HOUR function 229
hour of day (escalations) 125
I
If and Else actions 21, 46
if any requests match, push fields 100
if no requests match, push fields 99
implementation issues with server-side table
fields 167
INBULKTRANSACTION keyword 205
include fields (notification) 77
interactive guides, creating 156
interactive messages 69
interval (escalations) 124
Interval active link condition 31
K
keywords
APPLICATION 203
BROWSER 203
CLIENT-TYPE 203
CURRENTWINID 203
DATABASE 203
DATE 204
DEFAULT 204
EVENTSRCWINID 204
EVENTTYPE 204
FIELDHELP 204
FIELDID 204
FIELDLABEL 204
FIELDNAME 204
keywords (continued)
GROUPIDS 204
GROUPS 204
GUIDE 148, 204
GUIDETEXT 205
HARDWARE 111, 205, 236
HOMEURL 205
INBULKTRANSACTION 205
LASTCOUNT 205
LASTID 206
LASTOPENEDWINID 206
list of 203
LOCALE 206
NULL 206
OPERATION 206, 208
OS 111, 206, 236
ROLES 206
SCHEMA 207
SCHEMA-ALIAS 207
SERVER 207
SERVERTIMESTAMP 207
TCPPORT 207
TIME 207
TIMESTAMP 208
USER 208
VERSION 208
VUI 208
VUI-TYPE 208
WEEKDAY 208
keywords, values in qualifications 38
L
labels
changing color 58
continue button 147
guides and 66, 131, 145
LASTCOUNT keyword 205
LASTID keyword 206
LASTOPENEDWINID keyword 206
LEFT function 229
LEFTC function 229
LENGTH function 229
LENGTHC function 229
less than (or equal to) operators 200
LIKE operator 198
BMC Software Inc., Confidential
Index 279
BMC Remedy Action Request System 7.0
modal dialog boxes 78
modes
field mapping (Open Dialog action) 81
Modify
active link condition 28
filter condition 31
modifying
all matching requests (push fields) 100
first matching request (push fields) 100
guides 135
modulo operator 200
MONTH function 230
multiply operator 200
limitations
server-side table fields 167
LOCALE keyword 206
Locale reserved field 117
log files
arescl.log 196
debug mode, using 135
escalations 196
Log to File
action 52, 68
arerror.log 68
logging activity, guide 135
logging workflow activity 196
logical operators 198
looping through table fields
active link guides 153
filter guides 163
Lose Focus active link condition 31
LOWER function 229
LPAD function 229
LPADC function 230
LTRIM function 230
N
M
macros
executing through active link 106
name 107
MAX function 230
mechanism (notifications) 75
menu bar
items 169
menu items
active links 176
deleting 178
order, changing 175
Menu/Row Choice active link condition 30
menus
active link properties 171
active links 176
help 173
Merge Filter condition 31
Message action 52, 69
message numbers 72
MIN function 230
MINUTE function 230
280 Index
name, push fields 100
naming
guides 131
workflow objects 26
navigation guides, creating 156
nonnumeric values in filter qualifications 37
not equal operator 201
NOT operator 198
note (Message action) 70
notifications
ARNotification (field order) 78
cross-reference 76
email 75
user default 76
Notify action 52, 72
NULL keyword 206
NULL values
and relational algebra 210
in qualifications 38
in the AR System, using 210
number (Message action) 72
O
OLE, Automation active link action 52
open all (edit menu bar) 173
Open Dialog action 78
Open Window action
advanced functionality, defining 94
defining 78
description 52
BMC Software Inc., Confidential
Workflow Objects
Open Window action (continued)
dynamic fields, setting 94
extension, for views 80, 83, 86, 90
modify or display windows 84
report windows 88
restricted list, dialogs 82
restricted list, modify or display 88
restricted list, reports 93
restricted list, search or submit 84
search or submit windows 82
sorting fields 87
view extension 80, 83, 86, 90
views in dialog boxes, selecting 80, 83, 86, 90
Open Window View Extension 80, 83, 86, 90
OPERATION keyword 206, 208
operators
arithmetic 200
logical 198
precedence 201
qualifications and 198
OR operator 198
OS keyword 111, 206, 236
other mechanism (notification) 76
phase 1 actions 185
phase 2 actions 186
phase 3 actions 186
plug-ins 219
precedence, operator 201
$PROCESS$
commands 240
using 234
process results
$PROCESS$, using 234
assigning values from 234
processing
active links 182
filters 184
push data to another form 97
Push Fields action 97
advanced 101
advanced functionality, defining 101
defining 97
dynamic fields, setting 101
overview 53
restricted list 101
P
qualifications
building 34
conventions 35
database values 36, 40
escalations 34
filter examples 41
formatting conventions 35
keyword values 38, 203
nonnumeric values 37
NULL values 38
operators, list of 198
push fields 99
run if statements 32
set fields 116
system performance, improving 39
transaction values 36, 40
wildcards 202
workflow 32, 34
performance tips
escalations 124
optimize Push Field If qualifications 99
optimize Set Field If qualifications 117
qualifications 39
Run If statements 32
SQL searches 219
table loop selected rows only 140
table loops, enhancing 140
permissions
active links 21, 134
Run Process action 109
phasing of filters
exceptions 191
overriding 192
overriding, releasing pending operations 193
overriding, special naming convention 193
overview 185
Q
BMC Software Inc., Confidential
Index 281
BMC Remedy Action Request System 7.0
R
refreshing table fields 57
relational algebra and NULL values 210
REPLACE function 231
reporting
embedded, saving to disk 92
Open Window active link action 88
type (Open Window action) 91
requests
match (push fields) 100
no match (push fields) 99
restricted list
call guide action 140
Open Window action, dialogs 82
Open Window action, modify or display 88
Open Window action, reports 93
Open Window action, search or submit 84
Push Fields action 101
Set Fields action 119
workflow basics 28
Return/Table Dbl-Clk active link condition 30
reusable workflow 22
RIGHT function 231
RIGHTC function 231
ROLES keyword 206
ROUND function 231
RPAD function 232
RPADC function 232
RTRIM function 232
rules for SQL operations 218
Run If qualifications 32
Run Macro action 53, 106
Run Process action
defining 108
description 53
permissions 109
special commands 240
syntax guidelines 111
S
saving embedded reports to disk 92
SCHEMA keyword 207
SCHEMA-ALIAS keyword 207
Search active link condition 29
SECOND function 232
282 Index
security
databases 219
Direct SQL actions 219
sending events
additional considerations 263
CURRENTWINID keyword 203
Event condition 30
EVENTSRCWINID keyword 204
EVENTTYPE keyword 204
example procedure 264
LASTOPENEDWINID keyword 206
overview 262
PERFORM-ACTION-SEND-EVENT
command 255
SERVER keyword 207
servers, running processes in Windows 111
server-side table fields
creating a filter guide using 164
implementation 167
limitations 167
looping through table field 163
processing records in database, not server or
client 165
using 163
SERVERTIMESTAMP keyword 207
Set Default active link condition 29
Set Fields action
advanced 120, 121
advanced functionality, defining 120
defining 112
described 53
dynamic fields, setting 120
Filter API plug-in server 219
restricted list 119
walking a table field 269
shared guides, examples 137
shared workflow
deployable applications warning 22
described 22
examples 24
show Close button in dialog box 81
sort, Open Window action 87
BMC Software Inc., Confidential
Workflow Objects
toolbar buttons
appearance 174
deleting 178
order, changing 176
trace modes for workflow activity 196
trace modes, guide activity 135
transactions
database values, versus 40
values, checking 36
TRUNC function 233
SQL
See also Direct SQL
ANSI standards, using 64, 214
command (Direct SQL action) 65
result column (set fields) 216
results 217
rules for operation 218
status history 38
STRSTR function 232
STRSTRC function 232
Subject line for email in filters 77
Submit active link condition 28
Submit filter condition 31
SUBSTR function 233
SUBSTRC function 233
subtract operator 200
Sybase servers, working with 35
syntax guidelines 111
U
Un-Display active link condition 28
UPPER function 222, 233
Use First Matching Request Based On Locale
setting 117
USER keyword 208
users
default for notifications 76
name (notification) 73
T
Table Dbl-Clk active link condition 30
table fields
active links looping 153
filters looping 163
performance, improving 140
refresh results 57
walking a table 268
table loop selected rows only 140
take no action (push fields) 99
TCPPORT keyword 207
text
Message action 69, 70
notification 73
time criteria in escalations 124
TIME function 233
TIME keyword 207
times selected (escalations) 125
TIMESTAMP keyword 193, 208
tips
database processing in server-side table
fields 165
single filter guides, using 163
To 50
V
values
assigning in workflow 118
assigning with plug-in 219
qualifications and 37
set fields and 118
VERSION keyword 208
views
ARNotification 78
dialog boxes, selecting with Open Window
action 80, 83, 86, 90
VUI keyword 208
VUI-TYPE keyword 208
W
Wait action 53, 124, 146
walking a table field 268
warnings
active link permissions enforced in guides 134
active links and filters 69
ANSI SQL standards, using 64, 214
Application-Release-Pending command, use
with caution 250
BMC Software Inc., Confidential
Index 283
BMC Remedy Action Request System 7.0
warnings (continued)
Message action 70
shared workflow in deployable
applications 22
WEEKDAY
function 233
keyword 208
weekdays (escalations) 125
wildcards 202
Window Close active link condition 29
Window Loaded active link condition 30
Window Open active link condition 29, 183
windows
events. See Default Para Font> sending events
modify or display 84
report 88
search or submit 82
workflow 17
workflow
See also dynamic fields; workflow actions
$PROCESS$ commands 239
Basic properties 21
Basic tab 25
basics 26
events, sending 262
execution order 183
objects 14
qualifications 34
Restricted List 28
reusable 22
Run Process commands 239
shared 22
shared, samples of 24
types of actions 51
walking a table field 268
windows 17
workflow actions
See also dynamic fields; workflow
Call Guide 51, 53, 138
Change Field 51, 54
changing order 50
Close Dialog 61
Close Window 51, 61
Commit Changes 51, 62
creating 48
284 Index
workflow actions (continued)
creating and modifying 48
DDE 51, 63
deleting 50
Direct SQL 51, 64, 66, 144
Else 21
Exit Guide 51, 66, 144
Go To Guide Label 52, 66, 145
Goto 52, 66
If 21
Log to File 52, 68
Message 52, 69
modifying 49
Notify 52, 72
OLE Automation 52, 78
Open Dialog 78
Open Window 52, 78
Push Fields 53, 97
Run Macro 53, 106
Run Process 53, 108
Set Fields 53, 112
types 51
Wait 53, 124, 146
Y
YEAR function 233
BMC Software Inc., Confidential
*58468*
*58468*
*58468*
*58468*
*58468*
">