Action Request System 5.1 Developing AR System Applications

Transcription

Action Request System 5.1
Developing AR System
Applications: Advanced
PART NO: AR-512-DAAG-01
Copyright 2003 BMC Software, Inc. All rights reserved.
Remedy, the Remedy logo, all other Remedy 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.
Remedy, a BMC Software company, 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.
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 Remedy
If you need technical support for this product, or would like to request documentation for a product for
which you are licensed, contact Remedy 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 5.1 of the licensed program.
Remedy, a BMC Software company
2350 Bayshore Parkway
Mountain View, CA 94043
Tel 650.903.5200
Fax 650.903.9001
www.remedy.com
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Overview of This Manual . . . . . . . . . . . . . . . . . . . . . . . . 12
Action Request System Documents . . . . . . . . . . . . . . . . . . . 13
Chapter 1
Defining Guides and Guide Actions . . . . . . . . . . . . . . . . . . . 15
Creating Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Guide Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
The Call Guide Active Link or Filter Action . . . . . . . . . . . . . . . 17
The Exit Guide Active Link or Filter Action . . . . . . . . . . . . . . . 19
The Go To Guide Label Active Link or Filter Action . . . . . . . . . . . 20
The Wait Active Link Action . . . . . . . . . . . . . . . . . . . . . 21
Defining Guides
. . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Defining Guide Basics . . . . . . . . . . . . . . . . . . . . . . . . 24
Defining the Active Links or Filters in a Guide. . . . . . . . . . . . . . 25
Setting Permissions Properties . . . . . . . . . . . . . . . . . . . . 27
Building and Using Guide Change History . . . . . . . . . . . . . . . 27
Creating AR System Administrator Help for Guides . . . . . . . . . . . 27
Tracing Guide Activity . . . . . . . . . . . . . . . . . . . . . . . . 28
Modifying Guides. . . . . . . . . . . . . . . . . . . . . . . . . . 28
Deleting Guides . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Shared Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Active Link Guides . . . . . . . . . . . . . . . . . . . . . . . . . . 30
How Active Links Interact with Guides . . . . . . . . . . . . . . . . . 32
!3
Using Procedural Active Link Guides in Table Fields . . . . . . . . . . . 35
Using Interactive Active Link Guides. . . . . . . . . . . . . . . . . . 37
Filter Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Chapter 2
Using Microsoft OLE Automation in Workflow
. . . . . . . . . . . . . 41
The OLE Automation Active Link Action. . . . . . . . . . . . . . . . . 42
Sample Exercise: Using OLE Automation. . . . . . . . . . . . . . . . . 47
Linking to an ActiveX Control . . . . . . . . . . . . . . . . . . . . . 60
Understanding the Supported OLE Automation Servers . . . . . . . . . . 60
Chapter 3
Dynamic Data Exchange . . . . . . . . . . . . . . . . . . . . . . . . 63
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
DDE Time-Out Settings . . . . . . . . . . . . . . . . . . . . . . . . 65
Third-Party Applications and Macros . . . . . . . . . . . . . . . . . . 65
DDE Server Name and AR System Windows User Tool Path. . . . . . . . 66
Supported DDE Topic and Function . . . . . . . . . . . . . . . . . . 66
Example Program and Buffer . . . . . . . . . . . . . . . . . . . . . 67
The DDE Active Link Action . . . . . . . . . . . . . . . . . . . . . . 71
Assigning Active Link Values Through DDE . . . . . . . . . . . . . . . 76
Microsoft Excel Example . . . . . . . . . . . . . . . . . . . . . . . 77
Microsoft Word Example . . . . . . . . . . . . . . . . . . . . . . 82
DDE and Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Chapter 4
Using Full Text Search . . . . . . . . . . . . . . . . . . . . . . . . . 89
What Is Full Text Search?. . . . . . . . . . . . . . . . . . . . . . . . 90
FTS Functionality from Verity . . . . . . . . . . . . . . . . . . . . 91
Accruing and Weighting Results with FTS . . . . . . . . . . . . . . . 92
Sorting Requests by Weight . . . . . . . . . . . . . . . . . . . . . 93
Using the Ignore Words List . . . . . . . . . . . . . . . . . . . . . 93
Who Can Perform a Full Text Search? . . . . . . . . . . . . . . . . . . 94
Using FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Performing a Search in a Field Indexed for FTS . . . . . . . . . . . . . 94
Using the Accrue Operator . . . . . . . . . . . . . . . . . . . . . . 97
Combining FTS and Non-FTS Fields. . . . . . . . . . . . . . . . . . 99
Search Strategies and Issues. . . . . . . . . . . . . . . . . . . . . . 99
Limitations of FTS . . . . . . . . . . . . . . . . . . . . . . . . 101
4"
Developing AR System Applications: Advanced
Administering FTS . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Selecting Fields for FTS Indexing . . . . . . . . . . . . . . . . . . 102
Reindexing . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
The FTS Server (arservftd) Process . . . . . . . . . . . . . . . . . 104
Debugging FTS . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Assigning FTS Licenses to Users . . . . . . . . . . . . . . . . . . . . . 106
Defining a Field for FTS in the Field Properties Window . . . . . . . . . . 107
Estimating the Size of the FTS Index . . . . . . . . . . . . . . . . . 108
Moving the FTS Index . . . . . . . . . . . . . . . . . . . . . . . 108
Displaying FTS Weight in a Results List . . . . . . . . . . . . . . . 109
Chapter 5
Localizing AR System Applications . . . . . . . . . . . . . . . . . . . 111
Localizing AR System Forms and Applications . . . . . . . . . . . . . . 112
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Structure and Design . . . . . . . . . . . . . . . . . . . . . . . 112
Localizing Form Views. . . . . . . . . . . . . . . . . . . . . . . 113
Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Tasks for Localizing AR System Forms and Applications . . . . . . . . 115
Advanced Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 117
Selecting Languages During Installation of AR System . . . . . . . . . . . 117
Creating a Localized View of a Form . . . . . . . . . . . . . . . . . . . 119
Localizing the User Interface of a Form View . . . . . . . . . . . . . . . 120
Localizing View Components Through Export/Import . . . . . . . . . 121
Manually Localizing View Components . . . . . . . . . . . . . . . 122
Localizing Message Components of a Form View . . . . . . . . . . . . . 124
Automatically Localizing Messages . . . . . . . . . . . . . . . . . 125
Manually Localizing Messages . . . . . . . . . . . . . . . . . . . 126
Localizing Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Localizing Character Menus . . . . . . . . . . . . . . . . . . . . 132
Localizing File Menus . . . . . . . . . . . . . . . . . . . . . . . 132
Localizing Search Menus . . . . . . . . . . . . . . . . . . . . . . 133
Localizing Currency Types . . . . . . . . . . . . . . . . . . . . . . . 134
Localizing the Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . 134
Settings and Procedures for the Localized Environment . . . . . . . . . . 135
AR System Administrator Settings and Procedures . . . . . . . . . . . 135
!5
AR System Windows User Tool Preferences Settings . . . . . . . . . . 138
Accessing a Localized View of a Form in a Browser . . . . . . . . . . . 140
Chapter 6
Creating Reports for the Web and Exporting Data
. . . . . . . . . . . . 141
Reporting on AR System Data. . . . . . . . . . . . . . . . . . . . . . 142
Web Reporting Components . . . . . . . . . . . . . . . . . . . . 142
Web Reporting in AR System . . . . . . . . . . . . . . . . . . . . 143
Preference and Configuration Settings . . . . . . . . . . . . . . . . . . 144
AR System Windows User Tool Preferences . . . . . . . . . . . . . . 144
AR System Configuration Tool Options . . . . . . . . . . . . . . . 145
Crystal Web Settings . . . . . . . . . . . . . . . . . . . . . . . 146
System Data Source Name (DSN) . . . . . . . . . . . . . . . . . . 146
AR System Report Plug-in . . . . . . . . . . . . . . . . . . . . . 147
Defining the Web Reporting Environment . . . . . . . . . . . . . . . . 147
ReportType Form . . . . . . . . . . . . . . . . . . . . . . . . . 147
Report Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . 151
AR System Reports . . . . . . . . . . . . . . . . . . . . . . . . 151
Crystal Report Designer . . . . . . . . . . . . . . . . . . . . . . 151
ReportCreator Form . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Creating a Report Definition File . . . . . . . . . . . . . . . . . . 153
Saving Report Definition Files . . . . . . . . . . . . . . . . . . . 160
Editing Report Definition Files . . . . . . . . . . . . . . . . . . . 160
Report Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Report Form Entries . . . . . . . . . . . . . . . . . . . . . . . 161
Deleting Report Definition Files. . . . . . . . . . . . . . . . . . . 163
Running a Report on the Web. . . . . . . . . . . . . . . . . . . . . . 163
Directly Accessing the ReportSelection Form Through a Browser. . . . . 164
Reporting Using Table and Results List Fields . . . . . . . . . . . . . 166
Generating a Report Through an Open Window Active Link . . . . . . 169
Backwards Compatibility . . . . . . . . . . . . . . . . . . . . . . . . 172
Localized Reports . . . . . . . . . . . . . . . . . . . . . . . . . 172
Exporting AR System Data to a File . . . . . . . . . . . . . . . . . . . 173
Obtaining Data from an AR System Source . . . . . . . . . . . . . . 173
6"
Chapter 7
Importing and Exporting Object Definitions . . . . . . . . . . . . . . . 177
AR System Object Definitions. . . . . . . . . . . . . . . . . . . . . . 178
The AR System Definition (*.def) File Type . . . . . . . . . . . . . . 178
The AR System XML (*.xml) File Type . . . . . . . . . . . . . . . . 178
Exporting and Importing Definitions . . . . . . . . . . . . . . . . . . 179
Exporting Object Definitions . . . . . . . . . . . . . . . . . . . . 179
Importing Object Definitions . . . . . . . . . . . . . . . . . . . . 184
Exporting and Importing View Definitions . . . . . . . . . . . . . . . . 187
Chapter 8
Importing Data into AR System Forms . . . . . . . . . . . . . . . . . 189
Understanding the Import Process . . . . . . . . . . . . . . . . . . . 190
Understanding Data Mapping . . . . . . . . . . . . . . . . . . . 190
Understanding Preferences . . . . . . . . . . . . . . . . . . . . . 190
Preparing to Import . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Defining AR System Import Preferences . . . . . . . . . . . . . . . . . 194
Importing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Using a Saved Mapping File. . . . . . . . . . . . . . . . . . . . . . . 211
Using the Import Log File . . . . . . . . . . . . . . . . . . . . . . . 212
Chapter 9
Using Source Control . . . . . . . . . . . . . . . . . . . . . . . . . 215
Integrating Source Control with AR System . . . . . . . . . . . . . . . 216
Enforced and Advisory Modes . . . . . . . . . . . . . . . . . . . 217
Setting Up Source Control with AR System . . . . . . . . . . . . . . 218
AR System Source Control Options . . . . . . . . . . . . . . . . . 222
Adding AR System Objects to Source Control . . . . . . . . . . . . . 224
Exporting AR System Objects into Source Control . . . . . . . . . . . 225
Importing Definitions from Source Control. . . . . . . . . . . . . . 227
Removing Objects in Source Control. . . . . . . . . . . . . . . . . 230
Checking Objects In and Out of Source Control . . . . . . . . . . . . 231
Viewing History in Source Control . . . . . . . . . . . . . . . . . 233
Other Source Control Tasks . . . . . . . . . . . . . . . . . . . . 234
Chapter 10
Server Events Form . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Understanding the Server Events Form. . . . . . . . . . . . . . . . . . 238
How the Form Is Created . . . . . . . . . . . . . . . . . . . . . 238
Types of Events You Can Record . . . . . . . . . . . . . . . . . . 239
!7
Viewing the Server Changes You Recorded . . . . . . . . . . . . . . 242
Datatypes Values . . . . . . . . . . . . . . . . . . . . . . . . . 253
Using Server Events in Workflow . . . . . . . . . . . . . . . . . . . . 253
Chapter 11
Defining Packing Lists . . . . . . . . . . . . . . . . . . . . . . . . . 255
Using Packing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Creating Packing Lists . . . . . . . . . . . . . . . . . . . . . . . . . 256
Working in the Packing List Window . . . . . . . . . . . . . . . . . . 257
Specifying Packing List Basics . . . . . . . . . . . . . . . . . . . . 259
Defining Packing List Permissions . . . . . . . . . . . . . . . . . . 261
Defining Subadministrator Permissions for Packing Lists . . . . . . . . 261
Building and Using Packing List Change History. . . . . . . . . . . . 261
Creating AR System Administrator Help for Packing Lists . . . . . . . . 261
Saving Packing Lists in XML . . . . . . . . . . . . . . . . . . . . . . 262
Chapter 12
Creating and Using Web Services . . . . . . . . . . . . . . . . . . . . 265
Describing Web Services . . . . . . . . . . . . . . . . . . . . . . . . 266
Simple Object Access Protocol . . . . . . . . . . . . . . . . . . . 266
Message Styles . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Web Service Description Language (WSDL) File . . . . . . . . . . . . 267
Web Services and the AR System . . . . . . . . . . . . . . . . . . . . 267
Creating and Publishing a Web Service. . . . . . . . . . . . . . . . . . 268
Basic Web Services . . . . . . . . . . . . . . . . . . . . . . . . 270
Custom Web Services . . . . . . . . . . . . . . . . . . . . . . . 274
Writing Web Service Clients . . . . . . . . . . . . . . . . . . . . 281
Flow for Publishing a Web Service . . . . . . . . . . . . . . . . . . 281
Operation Types . . . . . . . . . . . . . . . . . . . . . . . . . 283
Consuming a Web Service . . . . . . . . . . . . . . . . . . . . . . . 289
Creating the Set Fields Filter to Import an External Web Service . . . . . 289
Flow for Consuming a Web Service . . . . . . . . . . . . . . . . . 292
Consuming a Web Service Published on the Same AR System Server . . . 292
Mapping to Simple and Complex Documents . . . . . . . . . . . . . . . 293
Simple Documents . . . . . . . . . . . . . . . . . . . . . . . . 293
Complex Hierarchical Documents . . . . . . . . . . . . . . . . . . 295
Using Join Forms in Web Services . . . . . . . . . . . . . . . . . . 304
8"
XML Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Simple XML Editing. . . . . . . . . . . . . . . . . . . . . . . . 306
Advanced XML Editing . . . . . . . . . . . . . . . . . . . . . . 313
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
SOAP Headers and Authentication . . . . . . . . . . . . . . . . . . . 318
Configuring with Internet Access Through a Proxy Server . . . . . . . . . 320
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Example 1: Publishing a Simple Flat Document . . . . . . . . . . . . 322
Example 2: Consuming a Simple Flat Document . . . . . . . . . . . . 327
Example 3: Publishing a Complex Document . . . . . . . . . . . . . 332
Example 4: Consuming a Complex Document. . . . . . . . . . . . . 349
Chapter 13
Understanding the Alert System
. . . . . . . . . . . . . . . . . . . . 357
Alert System Architecture . . . . . . . . . . . . . . . . . . . . . . . 358
Alert Events Form . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Viewing Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
CleanupAlertEvents Escalation . . . . . . . . . . . . . . . . . . . . . 360
Managing Registered Users . . . . . . . . . . . . . . . . . . . . . . . 360
Working with Versions of the AR System Prior to 5.0 . . . . . . . . . . . 361
Upgrading the Server But Not the Clients. . . . . . . . . . . . . . . 361
Upgrading or Installing Clients But Not the Server . . . . . . . . . . . 361
Enabling Alerts on the Web . . . . . . . . . . . . . . . . . . . . . . . 361
Chapter 14
The AR System ODBC Driver
. . . . . . . . . . . . . . . . . . . . . 365
Compatibility with ODBC Clients . . . . . . . . . . . . . . . . . . . . 366
Creating Multiple Data Sources . . . . . . . . . . . . . . . . . . . . . 366
Using Crystal Reports with AR System . . . . . . . . . . . . . . . . . . 368
Selecting Report Fields in Crystal Reports. . . . . . . . . . . . . . . 369
Considerations for Join Forms . . . . . . . . . . . . . . . . . . . 371
Limitations When Using Crystal Reports . . . . . . . . . . . . . . . 371
Using Microsoft Access with AR System . . . . . . . . . . . . . . . . . 372
Using Microsoft Excel with AR System . . . . . . . . . . . . . . . . . . 373
Chapter 15
Using the LDAP Plug-In . . . . . . . . . . . . . . . . . . . . . . . . 375
About LDAP Plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . 376
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 376
!9
Building AR System Forms For Directory Services. . . . . . . . . . . . . 377
Organizing Data . . . . . . . . . . . . . . . . . . . . . . . . . 377
Mapping an AR System Form to a Collection of Objects . . . . . . . . 378
Attaching Fields to Object Attributes. . . . . . . . . . . . . . . . . 382
Identifying Objects Uniquely . . . . . . . . . . . . . . . . . . . . 385
Supporting Object Creation . . . . . . . . . . . . . . . . . . . . 387
Summary of Fields . . . . . . . . . . . . . . . . . . . . . . . . 392
Working with the Distributed Server Option . . . . . . . . . . . . . . . 394
Conceptual Overview . . . . . . . . . . . . . . . . . . . . . . . 394
Directory Service Attributes and Object Classes . . . . . . . . . . . . 395
Enabling Your Data . . . . . . . . . . . . . . . . . . . . . . . . 395
DSO Field Definitions and Properties in the AR System . . . . . . . . . 397
Chapter 16
Using Action Request System from a Command Line . . . . . . . . . . . 401
Using the AR System Administrator Command Line Interface . . . . . . . 402
Guidelines for Using AR System Administrator CLI . . . . . . . . . . 402
AR System Administrator Commands and Options . . . . . . . . . . 403
AR System Administrator CLI Examples . . . . . . . . . . . . . . . 407
Using the AR System Import Command Line Interface. . . . . . . . . . . 409
Running arimportcmd on a UNIX Machine. . . . . . . . . . . . . . 409
Importing with Mapping. . . . . . . . . . . . . . . . . . . . . . 410
Importing Without Mapping . . . . . . . . . . . . . . . . . . . . 411
AR System Import CLI Examples . . . . . . . . . . . . . . . . . . 413
Using the AR System Windows User Tool CLI . . . . . . . . . . . . . . 414
AR System Windows User Tool CLI Example . . . . . . . . . . . . . 417
Appendix A
Special System Forms . . . . . . . . . . . . . . . . . . . . . . . . . 419
Special System Forms for AR System. . . . . . . . . . . . . . . . . . . 420
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
10 "
Preface
Audience
This guide is written for administrators of Action Request System® (AR
System). Administrator responsibilities include installing and maintaining
applications written for AR System, creating and implementing complete
applications, and making changes to applications as business processes
evolve.
This manual describes the advanced operations for those using AR System
Administrator (the Administrator Tool). It assumes familiarity with current
Microsoft Windows platforms.
Preface ! 11
Overview of This Manual
Chapter 1, Defining Guides and Guide Actions
Chapter 2, Using Microsoft OLE Automation in Workflow
Chapter 3, Dynamic Data Exchange
Chapter 4, Using Full Text Search
Chapter 5, Localizing AR System Applications
Chapter 6, Creating Reports for the Web and Exporting Data
Chapter 7, Importing and Exporting Object Definitions
Chapter 8, Importing Data into AR System Forms
Chapter 9, Using Source Control
Chapter 10, Server Events Form
Chapter 11, Defining Packing Lists
Chapter 12, Creating and Using Web Services
Chapter 13, Understanding the Alert System
Chapter 14, The AR System ODBC Driver
Chapter 15, Using the LDAP Plug-In
Chapter 16, Using Action Request System from a Command Line
Appendix A, Special System Forms
12 " Preface
Action Request System Documents
Title and Part Number
Description
Audience
Format
AR System Concepts Guide
AR-512-CG-01
Overview of AR System architecture and Everyone
features with in-depth examples;
includes information about other
AR System products as well as a
comprehensive glossary for the entire
AR System documentation set.
Applications: Basic
AR-512-DABG-01
Basic procedures for creating and
Administrators Print and
PDF
modifying an AR System application for
tracking data and processes.
Applications: Advanced
AR-512-DAAG-01
Advanced procedures for extending and Administrators Print and
customizing AR System applications.
PDF
Configuring AR System
AR-512-CFG-01
Server administration topics on
configuring servers and the mid tier, and
PDF
maintaining AR System.
Print and
PDF
Optimizing and Troubleshooting Server administration topics and
PDF
technical essays related to monitoring
AR System
and maintaining AR System for the
AR-512-OTG-01
purpose of optimizing performance and
troubleshooting problems.
AR System Database Reference
Guide
AR-512-DRG-01
Database administration topics and rules Administrators Print and
PDF
related to how AR System interacts with
specific databases; includes an overview
of the data dictionary tables.
AR System Distributed Server
Option Administrator’s Guide
AR-512-DSOG-01
Server administration and procedures for Administrators Print by
implementing a distributed AR System
special
server environment with the Distributed
order and
Server Option.
PDF
AR System C API Reference Guide Information about AR System data
structures, API function calls, and OLE
AR-512-CAPI-01
support.
Administrators Print by
and
special
Programmers order and
PDF
AR System Java API
Information about Java classes, methods, Administrators HTML
and variables that integrate with
and
AR System.
Programmers
Installing AR System
AR-512-IG-01
Procedures for installing and licensing
AR System.
PDF
Action Request System Documents ! 13
Title and Part Number
Description
Audience
Format
AR System Email Engine Guide
AR-512-EEG-01
Procedures for installing, configuring,
and using the AR System Email Engine.
special
order and
PDF
AR System Error Messages Guide List of AR System error messages with
expanded descriptions.
AR-512-EMG-01
and
special
Programmers order and
PDF
AR System Master Index
AR-512-MI-01
Combined index of all books.
Everyone
Print only
AR System Release Notes
AR-512-RN-01
New features list, compatibility lists,
international issues, open and fixed
issues.
Everyone
Print and
PDF
AR System Windows User Tool
Help
Procedures for using AR System
Windows User Tool.
Everyone
Help
menu
AR System Import Help
Procedures for using AR System Import. Administrators Help
menu
AR System Administrator Help
Procedures for creating and modifying
an AR System application for tracking
data and processes.
Administrators Help
menu
AR System Alert Help
Procedures for using AR System Alert.
Everyone
Help
menu
Unless otherwise noted, online documentation is available in Adobe Acrobat (PDF) format on AR System
product installation CDs and/or on the Customer Support web site.
14 " Preface
1
Defining Guides and Guide Actions
CHAPTER
This chapter describes how to use AR System Administrator to create
and modify active link guides and filter 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.
Also included in this chapter are descriptions of the various actions
used in guides: the Call Guide action, the Go to Guide Label action, the
Wait action, and the Exit Guide action.
!
Creating Guides on page 16
!
Guide Actions on page 17
!
Defining Guides on page 23
!
Active Link Guides on page 30
!
Filter Guides on page 38
Defining Guides and Guide Actions ! 15
Creating Guides
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?
!
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?
Step 2 Design the guide.
!
How many steps or dialog boxes will the guide require?
!
If you are using dialog boxes, lay them out.
!
Will you require data validation?
!
What will your prompts say?
Step 3 Create the active links or filters that you want to use within the guide. For
more information, see Guide Actions on page 17.
!
Use only one active link or filter for each step.
!
Although you can re-use active links or filters in your guide that were
designed for other applications, the best practice is to create new ones,
particularly active links, that do not have any Execute On conditions.
!
Keep track of any Go To Guide Label targets used.
Step 4 Create the guide.
a Set the appropriate guide basic specifications as described in Defining
Guide Basics on page 24.
b Specify the appropriate guide active links or filters as described in Defining
the Active Links or Filters in a Guide on page 25.
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.
16 "Chapter 1—Defining Guides and Guide Actions
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 Developing AR System Applications: Basic guide.
Step 5 Debug your guide before sending it to your user community.
!
Use active link logging to generate a list of active links that are executed
and the order in which they are executed.
!
Give visual cues to your user community as the guide executes through its
steps.
!
Create Message active link actions as temporary placeholders to
understand how your guide works.
Step 6 To send the completed guide to users through email, choose
File > Send To > User(s) as Shortcut.
Your 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 AR System Windows User Tool.
Guide Actions
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 page 20) 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 is also used for “looping” through rows in table fields
(also known as “table walk”). For more information, refer to Creating a
Guide that Walks You Through a Table Field on page 35
Defining 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.
Guide Actions ! 17
The fields required to define the Call Guide action appear. The following
figure shows these fields and an example of how a Call Guide active link
action might look after you complete the remaining steps in this procedure.
Figure 1-1: Call Guide Active Link Action
3 From the Call Guide field, select the server that contains the guide that you
want to start.
To add a new server to the list, click Add New Server to List twice. Then, type
the new server’s name and press Return.
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.
5 If you are using the Call Guide active link action to “walk” the rows of a table,
click the Table Loop check box, and choose from a list of available table fields.
The Table Loop check box does not appear if you are creating a filter.
6 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. It is not permitted to
call a guide based on another form on the web.
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.
Defining the Exit Guide Active Link or Filter Action
2 From the New Action list, select Exit Guide.
Figure 1-2: Exit Guide Active Link Action
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)
Guide Actions ! 19
The Exit Guide action appears in the Current Actions list.
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. 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 active
link that begins the series.
At some point 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 Defining Active Links or
Filters in a Guide on page 25.
Defining the Go To Guide Label Active Link or Filter Action
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.
Figure 1-3: 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.
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 AR System Windows User Tool so
that the user has an opportunity to interact with a field. After the user has
made 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.
Guide Actions ! 21
The Wait action has no effect when executed outside of a guide.
Use the following sequence of active links to create the typical form fill-in
steps:
!
Change Field (Set Focus)
!
Message (Prompt)
!
Wait
Defining the Wait Active Link Action
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 1-4: 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.”
The Wait action appears in the Current Actions list.
Defining Guides
This section describes how to set guide specifications using the tabs of the
Guide window, shown in the following figure.
Use the Guide window to create and modify guides. In this chapter, Guide
window refers to a Create Guide or Modify Guide window.
Figure 1-5: 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 AR System
Administrator.
Active Links
Defines the active links 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.
Defining Guides ! 23
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. In most cases, this help text
is a description of the guide, what it does, and how it is used.
Defining Guide Basics
Defining 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 AR System 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 the name that you want to appear in the Open dialog
box in AR System Windows User Tool.
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 will appear in the Open dialog
box in AR System Windows User Tool.
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.
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 The Exit Guide Active Link or Filter Action on
page 19 for more information.) As a result, you can only access those active
links 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. See Defining Guide Basics on page 24 for more
information.
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.
Defining the Active Links or Filters in a Guide
The active links or filters included within a guide determine the guide’s
functionality.
Defining 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 1-6 on page 26).
The Active Links (or Filters) in Form list shows all active links (or Filters)
associated with the forms that are selected in the Basic tab. The Active Links
(or Filters) in Guide list shows the active links or filters that are part of the
guide.
Figure 1-6: Guide Window —Active Link Tab
3 In the Active Links (or Filters) in Form list, select the active links or filters you
want to include in the guide, and then 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 this list. You can change the
order by using the up and down arrow Move buttons.
To remove active links or filters from the guide, select the appropriate action
in the Active Links (or Filters) in Guide list, and then click Remove.
If you want to use the same action 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 action 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, refer to the The Go To
Guide Label Active Link or Filter Action on page 20.
Setting Permissions Properties
Use the Permissions tab to define 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 and that those
permissions are enforced when running the guide. Any active link
in a guide to which a user does not have access will be skipped.
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).
Building and Using Guide Change History
AR System automatically records the owner of a guide, the user 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
Developing AR System Applications: Basic guide.
Creating AR System Administrator Help for Guides
To create or modify the help text for a guide, click the Help Text tab in the
Guide window. In most cases, 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 Developing AR System Applications: Basic guide.
Tracing 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 activated in AR System
Windows User Tool. For information about activating active link logging, see
AR System Windows User Tool help.
Modifying Guides
When modifying a guide, it is not necessary to send the modified guide to the
user community again. 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 user community to delete the guide
shortcuts from their desktop. If users try to start a guide after it has been
deleted from the server, they will receive an error message.
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 shipped when the guide is executed.
Note: Any changes you make to shared active links affect all guides and
forms that use them.
(See the Developing AR System Applications: Basic guide for instruction on
creating shared workflow.)
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, in this order, when deciding which
form to run on:
!
Search for the current form.
!
If current form belongs to the guide, run the guide against the current
form.
!
If current form does not belong to the guide, open a new window with
reference form and run the guide. This functionality is not supported by a
web client, see Shared Guide Example 3.
The following examples illustrate Shared Guide behavior. Assume you have
created guide X and shared it with forms A, B, and C:
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.
3 Guide X will be executed upon form A.
1 Create a Call Guide active link action for forms A, B, and C.
2 Open form C and execute the Call Guide action.
3 Guide X will be executed upon form C.
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.
4 A new window will open with the reference form B.
5 Guide X will be executed upon form B in a new window.
This particular functionality is not supported by a web client. On the web you
can achieve the same effect using the Open Window action and calling the
guide on the Window Open execute on condition. In this case, the form can
be opened in any mode.
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.
Active Link Guides
Possible uses of active link guides include the following:
“Interactive guides” that 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
AR System Windows User Tool, but not through a web 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, refer to
Using Procedural Active Link Guides in Table Fields on page 35.)
An Active Link guide can be executed through the Open dialog box in
AR System Windows User Tool (File > Open), through workflow, or
through an email attachment that users can then drag as a shortcut to their
Desktop.
There are several different 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, refer to The Call Guide Active Link or Filter Action on page 17.
!
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 name that is
not recognized in the underlying form, the guide opens a registration
dialog box for the user. If the user clicks Yes in the dialog box, another
guide opens for the user to enter registration information. When the user
completes all the necessary information, the guide closes and enters the
information back into the first guide.
The following figure shows an example of an interactive guide using the
Go To Guide Label.
Figure 1-7: Guide Using Go To Guide Label Active Link Action
For more information about the Go To Guide Label action, refer to The
Go To Guide Label Active Link or Filter Action on page 20.
Active Link Guides ! 31
!
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 the logic of these conditions, you
may decide to exit the guide or all guides. The Exit Guide active link action
is designed to quit the guide under the conditions you specify.
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, refer to The Exit Guide
Active Link or Filter Action on page 19.
How Active Links Interact with Guides
The majority 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 Table 1-1 on page 33 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
the Developing AR System Applications: Basic guide.
Table 1-1: How Active Links Interact with Guides (Sheet 1 of 3)
Execute On
Condition
Interaction
Submit
After Submit
Search
Modify
After Modify
Display
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.
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.
Execute On
Condition
Interaction
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
AR System Windows User Tool. 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).
Undisplay
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.
Button/Menu Item Active links that have this condition are honored when a
guide waits. AR System Windows User Tool 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
These conditions can be triggered only when a guide is
Dbl-Clk
executing a wait. If the field focus is changed by an action
Menu/Row Choice associated with the On Return trigger, then the Wait
condition on the guide ends.
Execute On
Condition
Interaction
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, the user cannot change field focus unless
the running guide is first 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. Then the newly focused
field’s Gain Focus condition is 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, the user
cannot change field focus unless the running guide is first
terminated.
Using Procedural Active Link Guides in Table Fields
Active link guides are useful for creating workflow that steps through the
rows in a table field. 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.
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, refer to the Developing AR System
Applications: Basic guide.
Creating a Guide that Walks You Through a Table Field
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.
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.
3 Configure the Basic tab of the active link:
!
Run If: ‘Column’ = $USER$
The test here is to fire the active link only if the value of the Submitter field is
set to the person who is logged in to AR System Windows User Tool.
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 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
9 Select the Table Loop check box.
This action will activate the guide and “loop” it through the rows in the table
field.
10 Create a second active link action.
!
Action: Exit Guide
This action will exit the guide after it loops through the rows.
11 Log in to AR System Windows User Tool as user Demo and open the Loop
Test form.
12 As a test, create several tickets, but only one with Demo as the value of the
Submitter field.
13 Click the table field to refresh it. The tickets you just created will appear as
rows.
14 Click the button field on the form.
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 an end user, a guide looks like any other application that you open
in AR System Windows User Tool. A Guide includes the Stop Guide and
Continue buttons, as shown in the following figure.
Figure 1-8: 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 AR System Windows User Tool. To create
the typical steps in a navigation-style guide, you would 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.
!
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 Action—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 web browser. Instead, you have to create dialog
boxes for user-interaction within the guide. For more information about
using a display-only form as a dialog box, refer to the Developing AR System
Filter Guides
Filter guides are used to create re-usable components of filter workflow by
adding computational subroutines within filter processing. This provides for
more sophisticated workflow solutions and allows easier re-use 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, refer to The Call
Guide Active Link or Filter Action on page 17.
!
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, refer to The Exit Guide Active Link or Filter Action on page 19.
!
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 Goto action, refer to The Go To Guide Label
Active Link or Filter Action on page 20.
Filter guides allow a developer to group a set of workflow 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
Filter Guides ! 39
By design, each filter will fire in its own execution order, based on which
events trigger the filter action.
By contrast, a filter guide Foo with an execution order of 50 could call these
filters, in the following defined sequence:
Filter Name
A
C
E
This same filter guide Foo 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 fire in Phase 1, a Push Fields action in Phase 2, and so
on. For more information about filter phases in AR System, refer to
the Developing AR System Applications: Basic guide.
You use essentially the same procedures to create filter guides as you would
active link guides. For more information, refer to Defining Guide Basics on
page 24.
2
CHAPTER
Using Microsoft OLE Automation in
Workflow
You can use the OLE automation active link action to integrate
AR System Windows User Tool with an external automation server.
The OLE automation action is just like any other active link
action—when it executes, it carries out the specified automation
sequence on the specified automation server.
To demonstrate this functionality, this chapter describes a process for
creating an OLE automation active link that performs a spellcheck
using Microsoft Word.
For more information on automation in AR System, see the AR System
C API Reference Guide.
!
The OLE Automation Active Link Action on page 42
!
Sample Exercise: Using OLE Automation on page 47
!
Linking to an ActiveX Control on page 60
!
Understanding the Supported OLE Automation Servers on page 60
Using Microsoft OLE Automation in Workflow ! 41
The OLE Automation Active Link Action
Use the OLE Automation action to share functionality between applications
that support OLE. When using this action, AR System acts as an OLE
automation controller client to an OLE server.
The following procedure describes how to implement OLE automation
within AR System. Like SQL, you should debug OLE automation calls in a
full OLE and COM development environment and then use that knowledge
to build the same calls in AR System Administrator.
A sample exercise can be found on page 47. This example uses OLE
automation to create a form and active link to open Microsoft Word, spell
check text in a field in that form, and return the corrected text to the field.
Note: If you are designing an active link for a form that is also used by clients
on platforms other than a PC, verify that the current platform is a PC
as a condition of activating the DDE action. To do this, include a
qualification that uses the $HARDWARE$ keyword to verify the current
platform. See Developing AR System Applications: Basic guide for more
information on building qualifications.
Defining the OLE Automation Active Link Action
With the Server Window open:
1 Choose File > New Server Object
The New Server Object dialog box appears.
2 Select Active Link from the New Server Object field.
3 Click OK.
The Create Active Link dialog box appears.
4 Set up the conditions in the Basic tab.
5 Click the If Action tab, or click the Else Action tab.
6 From the New Action list, select OLE Automation.
42 "Chapter 2—Using Microsoft OLE Automation in Workflow
The fields required to define the OLE Automation action appear. The
following figure shows these fields and an example of how an OLE
Automation active link action might look after you complete the remaining
steps in this procedure.
Figure 2-1: OLE Automation Active Link Action
7 If you want animated Genie assistance as you complete the rest of the
procedure, select the Genie Help check box.
8 From the Automation Servers list, select the appropriate OLE server or
control:
!
OLE Local Servers—Lists the OLE servers on your machine.
!
OLE Automation Control—Lists the controls on your machine.
Because remote automation is not supported, users can access only the OLE
active link Automation action if the same OLE components selected in AR
System Administrator also exist on their computers.
9 Double-click the appropriate server or control.
The list of objects defined in the OLE server is displayed under the Type
library tree hierarchy.
10 From the Type Library Information list, select the Objects folder.
The OLE Automation Active Link Action ! 43
A list of objects defined for the selected server or control appears. You can
also select the Enumerators, Structures, Objects, Aliases, or Unions
directories to view display-only reference information for the selected server
or control. If the selected server or control has at least one of these items
defined for it, you will only be able to open the Enumerators, Structures,
Objects, Aliases, or Unions directories.
11 From the Objects folder, select the appropriate object.
A Methods folder that contains all of the methods for the selected object
appears.
12 Open the Methods folder, select the appropriate method, and then click Add
Method.
The selected method is displayed as an equation in the Method field. At the
same time, the method is added to the Method folder in the Parameter List
as a tree control. You can use the tree control to define variables that make
up the method parameters and return value. As you define each method
parameter and the return value through the Parameter List tree control, the
Method field displays the results of each selection you make.
When you look at the method equation in the Method field, each item that
you can specify has the place holder Type in value here. If Type in value here
is not in the method equation where you would expect to find the return
value or a method parameter, it means that a return value or method
parameters do not exist for the selected method.
If an OLE method returns an object, you can nest the methods of the
returned object. That is, if when you call a method on object A, object B is
returned, you can nest these methods using the syntax:
Return Value = A.B(<parameter 1>, <parameter 2>, ...).
13 To define the method parameters, click the plus sign to the left of the method
name, click the plus sign to the left of Parameters, and then click the plus sign
to the left of the appropriate parameter name.
The words Type in value here appear below the selected parameter and
represents the item that you want to use as the parameter when the method
is called. The parameter value must be of the data type specified in the
parameter name. You can define the parameter in one of the following ways:
!
Select Type in value here, click again to activate edit mode, and then type
in the appropriate parameter value.
!
Right-click Type in value here, and choose from a list of field values or
keywords.
!
Click Type in value here, select a method from the Type Library
Information list that has a return value that is compatible with the
parameter data type, and then click Add Method.
Your selection replaces the Type in value here place holder of the Method
equation in the Method field.
!
Optional parameters are displayed within brackets ([ ]). AR System
Windows User Tool will substitute default values for the optional
parameters when the AR System Windows User Tool is run if you leave
the parameters blank.
Repeat step 14 until every parameter for the selected method has been
defined. If you set a parameter with a method, as described in step 9, and the
method you choose has parameters, you must define these parameters as
well.
14 To define the method return value, click the plus sign to the left of the
Method Returns, and click the plus sign to the left of Return Value.
Type in value here appears and represents the variable that you want to use
as the return value when the method is called.
15 Right-click Type in value here, and choose from a list of field names.
The return value must be of the data type specified in Return Value. Your
selection replaces the Type in value here place holder of the Method
equation in the Method field.
In cases where the return value is a pointer, the only way to make use of the
returned object is to cascade or nest a method of the object being returned.
16 To delete a method, select the method in the Parameter list tree control, and
click Delete Method.
!
The OLE Automation action appears in the Current Actions list.
The following figure shows an example of an active link that is already
created, and explains the different sections of the If Action tab. Explanatory
text follows the figure.
The OLE Automation Active Link Action ! 45
Active Link
Actions
Click the arrows
to rearrange
actions.
Automation
Servers
Object
Method
As you select methods,
they are displayed in a tree
view. If they have
parameters or return
values with them, you can
enter them in this list.
When you update a value in the Parameter List, it is
reflected in the Method field.
Figure 2-2: OLE Automation Active Link
Included in the Type Library Information list are enumerators, structures,
objects, aliases, and unions. OLE automation servers define these special data
types, which can be used as parameters or return types in the method calls
defined in the objects. Some of these data types are used for display purposes
only and are not useful to the OLE automation author. However, objects
contain methods defined within them, you will be using these to create an
OLE automation active link action.
When you expand the objects listed in the Type Library Information list, all
the methods for each object are displayed in a tree view. The type library
information is identified by using the following alphabetical order):
!
Object: Red icon (see Figure 2-2 on page 46)
!
Method: m
!
Parameter: p
!
Return Value: R
Sample Exercise: Using OLE Automation
The following exercise describes how to create a form and an active link to
open Microsoft Word, spell check text in a field in that form, and return the
corrected text back to the field.
Note: This example is only a partial solution that does not cover all aspects
of this problem. For a more complete example that uses a different
approach, see the Sample:SpellCheck active link in the ClassCentral
sample application.
To complete the exercise, you must understand how objects, methods,
parameters, and return values are identified in the If Action or Else Action
tabs for creating OLE automation active links.
Creating an OLE Automation Action Link—Procedure 1: Creating the
Form
1 In AR System Administrator, select a server, and choose File > New Server
Object.
2 Select Regular Form, and click OK to create a new form.
3 Create a new button located under the Short Description field, with the
following properties:
!
Button Label: Spell check
!
Button Name: Spell check
4 Using the Permission tabs, set permissions to Public for the Short
Description field and the Spell Check button.
5 Hide the other fields on the form and move the position of the Short
Description field and Spell Check button, if desired.
6 Name the form OLE-Testform, and save it.
Your form appears similar to Figure 2-3 on page 48.
Sample Exercise: Using OLE Automation ! 47
Figure 2-3: OLE -Testform
7 Refer to the following procedures to create the active link and to set up the
actions for the active link for the Spell Check button.
Creating an OLE Automation Action Link—Procedure 2: Defining the
Active Link
1 In AR System Administrator, select a server, and choose File > New Server
Object.
2 Select Active Link, and click OK to create a new active link.
3 Enter OLE-APP-CheckSpell in the Name field.
This is the name of the OLE automation active link.
4 Select OLE-Testform, which is the form that you created by using the
procedure Creating an OLE Automation Action Link—Procedure 1: Creating
the Form on page 47.
5 Select the Button/Menu Item check box.
6 Select the Spell Check button from the Field list, as shown in Figure 2-4 on
page 49.
This specifies that the active link is invoked when a user clicks the Spell Check
button.
Figure 2-4: Create Active Link Dialog Box
Note: The following procedures assume that you collapse each list after you
make selections from them.
Creating an OLE Automation Action Link—Procedure 3: Defining Action 1
The action described in this procedure makes Microsoft Word visible. When
you create this action for the active link, you will construct the following
objects:
_Document Object::Application*Application( )
_Application Object::void Visible( 1 )
1 In the If Action tab of the Create Active Link dialog box, select OLE
Automation from the New Action list.
2 In the Automation Servers list, expand OLE Local Servers.
3 Double-click the Microsoft Word Document local server.
The type library information appears in the Type Library Information list.
4 Expand Objects in the Type Library Information list.
The list of objects appear for the Microsoft Word Document local server.
5 Expand _Document Object in the Type Library Information list, and expand
Methods below it.
6 Select the Application* Application( ) method, and click Add Method.
Application appears in the Parameter List.
7 Select Application in the Parameter List.
By selecting Application in the Parameter List, you are specifying that the
next method that you select will be placed below it. This is a new OLE
automation action; yet, AR System Windows User Tool treats this as a
continuation of the previous stream of OLE method calls. The division of the
stream into multiple actions is arbitrary.
8 Expand _Application Object in the Type Library Information list, and
expand Methods below it.
9 Select the void Visible(boolean rhs) method, and click Add Method.
The Visible method appears in the Parameter List below Application.
10 Set parameters for the void Visible(boolean rhs) method by using the
Parameter List.
a Expand Visible.
b Expand Parameters.
c Expand rhs::Type->boolean.
d Select ?Type in Value here and enter 1.
This sets the Boolean parameter to 1 (TRUE).
Note: To add a field or keyword as the parameter value, right-click ?Type in
Value here to open a list of form fields or keywords. Select the
appropriate choice from the list.
The Parameter List appears as shown in Figure 2-5 on page 51.
Figure 2-5: Parameter List
11 Click Add Action and save the action.
The action described in this procedure transfers the contents of the Short
Description field to Microsoft Word. When you create this action for the
active link, you will construct the following objects:
_Document Object::Sentences( )
Sentences Object::Range*First( )
Range Object::void InsertAfter (BSTR Text)
Set text to $Short Description$
1 Select OLE Automation from the Current Actions list, and select OLE
By selecting the first action, the next action that you create is placed below it.
This is a new OLE Automation action; yet, AR System Windows User Tool
treats this as a continuation of the previous stream of OLE method calls. The
division of the stream into multiple actions is arbitrary.
2 Expand _Document Object in the Type Library Information list and expand
Methods below it.
3 Select the Sentences* Sentences( ) method, and click Add Method.
Sentences appears in the Parameter List.
4 Select Sentences in the Parameter List.
By selecting Sentences in the Parameter List, you are specifying that the next
method that you select will be placed below it.
5 Expand Sentences Object in the Type Library Information list, and expand
Methods below it.
6 Select the Range*First( ) method, and click Add Method.
First appears in the Parameter List below Sentences.
7 Select First in the Parameter List.
By selecting First in the Parameter List, you are specifying that the next
8 Expand Range Object in the Type Library Information list, and expand
Methods below it.
9 Select the void InsertAfter (BSTR Text) method, and click Add Method.
InsertAfter appears in the Parameter List below First.
10 Set parameters for InsertAfter by using the Parameter List.
a Expand InsertAfter, and expand Parameters below it.
b Expand the Text:Type -> BSTR parameter.
c Select ?Type in Value here, right-click, and select Fields> Short
Description.
The values in the Method field and in the Parameter List are shown in
Figure 2-6 on page 53.
Figure 2-6: Action Two Values
11 Click Add Action, and save the action.
The action described in this procedure spell checks the contents of the Short
Description field. When you create this action for the active link, you will
construct the following object:
_Document Object:void CheckSpelling( )
1 Select the last OLE Automation from the Current Actions list, and select OLE
By selecting the last action in the list, the next action that you create is placed
below it.
Methods below it.
3 Select the void CheckSpelling method, and click Add Method.
CheckSpelling appears in the Parameter List. It is not necessary to change the
parameters for it because they are optional.
Note: Braces [ ] around the parameters in the Parameters List indicate that
the parameters are optional.
If you expand the CheckSpelling method and Parameter, the following values
are shown in the following figure.
Figure 2-7: Action Three Values
The action described in this procedure selects the entire contents of the text
in Microsoft Word in preparation for sending it back to the Short
Description field. When you create this action for the active link, you will
construct the following objects:
_Application Object::Selection* Selection( )
Selection Object::void WholeStory( )
1 Select the last OLE Automation in the Current Actions list, and select OLE
below it. This is a new OLE automation action; yet, AR System Windows
User Tool treats this as a continuation of the previous stream of OLE method
calls. The division of the stream into multiple actions is arbitrary.
Methods below it.
next method that you select will be placed below it.
6 Select the Selection* Selection( ) method, and click Add Method.
Selection appears in the Parameter List below Application.
7 Select Selection in the Parameter List.
By selecting Selection in the Parameter List, you are specifying that the next
8 Expand Selection Object in the Type Library Information list, and expand
Methods below it.
9 Select the void WholeStory( ) method, and click Add Method.
WholeStory appears in the Parameter List below Selection.
The values in the Method field are shown in Figure 2-8 on page 56.
Figure 2-8: Action Four Values
10 Click Add Action and save the action.
The action described in this procedure sends the selected text back to the
Short Description field. When you create this action for the active link, you
will construct the following objects:
_Application Object::Selection* Selection( )
Selection Object::BSTR Text( )
Set Text to $Short Description$
1 Select the last OLE Automation in the Current Actions list, and select OLE
below it. This is a new OLE Automation action; yet, AR System Windows
User Tool treats this as a continuation of the previous stream of OLE method
calls. The division of the stream into multiple actions is arbitrary.
Methods below it.
next method that you select will be placed below it.
6 Select the Selection* Selection( ) method, and click Add Method.
Selection appears below Application in the Parameter List.
7 Select Selection in the Parameter List.
By selecting Selection in the Parameter List, you are specifying that the next
8 Expand Selection Object in the Type Library Information list, and expand
methods below it.
9 Select the BSTR Text( ) method, and click Add Method.
Text appears in the Parameter List below Selection.
10 Set the return values by using the Parameter List.
a Expand Method Returns.
b Expand Return Value -> BSTR.
c Select ?Type in Value here, right-click, and select Fields> Short
Description.
The values in the Method field, and in the Parameter List are shown in
Figure 2-9: Action Five Values
Your active link is now complete and you are ready to test it (by using
Microsoft Word) as described in Creating an OLE Automation Action
Link—Procedure 8: Testing the Active Link
Ensure that you distribute the local OLE automation server to users’
machines so that the active link executes without error. Also, ensure that the
local OLE automation server is registered on the users’ machines by using the
Regsvr32 utility (this should occur during the installation of Microsoft
Office). For more information about registering local OLE automation
server controls, refer to your Microsoft OLE automation documentation.
Note: You can modify and delete active link actions by selecting the action
from the Current Actions list, and clicking Modify Action or Delete
Action.
Creating an OLE Automation Action Link—Procedure 8: Testing the Active
Link
1 Open AR System Windows User Tool.
2 Choose File > Open.
3 In the Open dialog box, select the OLE-Testform that you created in the
sample exercise.
4 Enter text in the Short Description field (misspell the text, purposely).
5 Click Spell Check.
The Search OLE-Testform appears as shown in the following figure, which
enables the user to correct the spelling of the text in the Short Description
field by using Microsoft Word.
Figure 2-10: Spell Check Form
6 Correct the spelling by using the Microsoft Word spell checking feature.
7 Exit Microsoft Word, and return to AR System Windows User Tool.
8 View the changed text.
Linking to an ActiveX Control
Creating a callable ActiveX control in Visual Basic (or any other language) is
simple. Ensure that the class module and functions for your control are
public and that you give a recognizable name to the interface being exposed.
If you create an ActiveX DLL in Visual Basic, ensure that you follow these
rules:
!
Give a unique and recognizable name to the interface exposed. Each class
module defined becomes an interface object.
!
Give a unique and recognizable name to the project name.
!
Ensure that you create a DLL and register the DLL in the system by using
the RegSvr32 utility.
When you are using an ActiveX control as an OLE server, you perform the
same procedure described in Sample Exercise: Using OLE Automation on
page 47; however, you select an ActiveX control from the list of OLE
Automation Controls, rather than the list of local OLE servers.
Understanding the Supported OLE Automation Servers
AR System Administrator shows OLE servers defined on the administrator
machine. AR System supports:
!
OLE servers on local computers—Servers that run in the same processing
space as their client.
!
In-process servers or controls—Servers or controls that run in the process
space of the client's process space.
When AR System Administrator browses the administrator machine and
selects OLE servers on local computers and in-process servers registered on
that machine, it uses the following rules to select OLE servers to appear for
use with AR System. The OLE server must have the following properties
listed under its registry entry:
!
TypeLib-listing the typelib IID or Programmable
!
InProcServer or LocalServer entry
When the servers have any of the following properties, they are not displayed
in AR System Administrator:
!
The in-process server is a system component and not an application OLE
automation server.
!
The OLE server is an OLE 1.0 control.
!
All 1.0 OLE controls have an Ole1Class entry.
!
The server entry has an autoconvert attribute.
An OLE component has the following registry entries for in-process servers
under the InProcServer32 entry:
!
ole32.dll
!
oleprx32.dll
!
ole2pr32.dll
!
olecnv32.dll
!
oleaut32.dll
An OLE component has the following registry entries for in-process servers
under the InProcServer entry:
!
ole2prox.dll
!
ole2.dll
!
ole2disp.dll
Understanding the Supported OLE Automation Servers ! 61
3
Dynamic Data Exchange
CHAPTER
This chapter provides the following information about how dynamic
data exchange (DDE) in Microsoft Windows functions with AR
System:
!
Overview on page 64
!
DDE Time-Out Settings on page 65
!
Third-Party Applications and Macros on page 65
!
The DDE Active Link Action on page 71
!
Assigning Active Link Values Through DDE on page 76
!
DDE and Reports on page 86
Dynamic Data Exchange ! 63
Overview
Dynamic data exchange (DDE), a part of Microsoft Windows, is a form of
interprocess communication that uses shared memory to exchange data
between applications.
Action Request System uses DDE to communicate with third-party
Windows applications, such as Excel, Word, and Visual Basic. Typically, this
is done through active links from AR System or by various actions in the
third-party applications. AR System can integrate data with third-party
applications by using DDE in the following ways:
!
Using DDE and active links, you can:
!
Send information to another Windows application. For example, you
can send the value in a form field to a spreadsheet cell or a word
processor bookmark.
!
Send a request for specific information in another Windows
application to change the value of a field in a form. For example, you
can import data from a spreadsheet cell to a form field.
In AR System Administrator, you specify a DDE command and a trigger
action for an active link. Users activate the active link from the toolbar or
through actions in AR System Windows User Tool.
!
Using DDE and AR System Windows User Tool, users can send a report
to another Windows application and cause the application containing the
AR System report to open. For example, you can send an AR System
report to a word processor file and have the word processor application
open with the report displayed.
!
Using DDE and a third-party application, the third-party application can
execute a macro to launch AR System Windows User Tool, if necessary.
For example, you can write a program that opens both AR System and a
form.
For more information about DDE, refer to the Microsoft Windows
documentation. To integrate with another application, refer to that
application’s documentation. For information about defining a DDE active
link operation, see The DDE Active Link Action on page 71.
64 "Chapter 3—Dynamic Data Exchange
DDE Time-Out Settings
The Action Request System DDE operations have a time-out setting
associated with them in the ar.ini file. The time-out setting is the amount of
time that AR System Windows User Tool waits for a response from the
third-party application. If there is no response after this set time, the DDE
operation is not completed. A time-out message is then displayed.
The default DDE time-out setting is 30 seconds. Until you add the [DDE]
section label and the time-out setting, they do not exist in your ar.ini file. If
you want to change the default value, add the following information to your
ar.ini file:
AppResponseTimeout=<N>
TransactionTimeout=<N>
<N> is the new DDE time-out setting in seconds.
Note: Before you change this value, understand that if you specify less time
than the operation normally requires, the operation will always
generate a time-out message. Also, if you specify more time than is
required, you might have to wait longer than necessary for the affected
operations to time out.
Third-Party Applications and Macros
Third-party applications can use a DDE program to send a request to execute
a macro in AR System Windows User Tool. This program must include the
following:
!
DDE server name of AR System Windows User Tool
!
Path for AR System Windows User Tool
!
DDE topic AR System Windows User Tool supports
!
DDE function AR System Windows User Tool supports
DDE Time-Out Settings ! 65
DDE Server Name and AR System Windows User Tool Path
The DDE server name and the path of AR System Windows User Tool are
added to your win.ini file when you install Action Request System for
Windows. This information is added to the [AR System] section, as follows:
AppName=ARUSER-SERVER
ProgramPath=<path_to_aruser>\aruser.exe DDEcall <path_to_aruser>
Each field means the following:
!
AppName—The DDE server name for AR System Windows User Tool.
!
ProgramPath—The path for AR System Windows User Tool.
The path is needed so that a third-party application can find and start
AR System Windows User Tool. Use this field exactly as shown.
Also, you must complete one of the following tasks in your DDE program
before executing AR System Windows User Tool:
!
Set your PATH environment variable to the AR System Windows User
Tool directory.
!
Change to the AR System Windows User Tool directory.
Supported DDE Topic and Function
AR System Windows User Tool supports the DoExecMacro DDE topic and
the RunMacro DDE function. DoExecMacro enables you to use DDE to run
macros in AR System through third-party applications. The RunMacro
function creates a buffer that contains the path and name of the macro along
with any needed parameters. This buffer contains the information that
AR System Windows User Tool needs to find and run the macro.
The syntax of the buffer that is recognized by AR System Windows User Tool
is as follows:
RunMacro(<macro_path>,<macro_name>,
[<paramater_name_1=parameter_value_1>,
<parameter_name_2=parameter_value_2,...>]
Each parameter means the following:
<macro_path>
The path for the macro. This parameter is required.
<macro_name>
The name of the macro. You do not need to use
quotation marks, even if the name contains blank
spaces. This parameter is required.
<parameter_name>
The name of any prompt parameter in the macro. This
parameter is optional.
<parameter_value>
The value you want to substitute for the current
parameter. You must supply a parameter value for
every specified <parameter_name>.
Example Program and Buffer
The following example C program sends a DDE message to AR System
Windows User Tool, instructing it to run a macro called SendMessage found
in the c:\app\macro directory. This macro requires two parameters:
!
The name of the user that receives the message
!
The message text
The RunMacro function in this example creates the following buffer:
[RunMacro(c:\app\macro,SendMessage,
Name=John Smith,Contents=Don’t forget our meeting on friday)]
/* DoDDEInit -- This routine initializes dde conversation. It must be called before any
dde conversation can happen.
*/
BOOL WINAPI DoDDEInit(void)
{
BOOL bResult = FALSE;
// Read the path to the aruser.exe
if (GetProfileString("ARSYSTEM",
"ProgramPath","",szARuserPath,
sizeof(szARuserPath) - 1) == 0 ) {
// display an error message if aruser is not installed.
return FALSE;
}
// Initialize the dde client
if (lpDdeProc = MakeProcInstance((FARPROC)DdeCallBack, hInst)) {
idInst = 0;
if (DdeInitialize((LPDWORD)&idInst, (PFNCALLBACK)
Third-Party Applications and Macros ! 67
lpDdeProc, DDE_INIT_FLAGS, NULL) == DMLERR_NO_ERROR){
Hszize();
bResult = TRUE;
}
else
FreeProcInstance((FARPROC)lpDdeProc);
}
return (bResult);
} // DoDDEInit()
/* DoDDEUnInit -- Uninitializes applications and frees call back
*/
VOID WINAPI DoDDEUnInit(void)
{
if (hConv) {
DdeDisconnect(hConv);
hConv = NULL;
}
if (lpDdeProc) {
DdeUninitialize(idInst);
FreeProcInstance((FARPROC)lpDdeProc);
}
UnHszize();
} // DoDDEUnInit()
/* Hszize -- This creates often used global hszs from standard global strings.
It also fills the hsz fields of the topic and item tables.
*/
static void Hszize(void)
{
char szServerName[MAX_TOPIC + 1];
// Get the name of server in string handle format
GetProfileString("ARSYSTEM","AppName","",
szServerName,MAX_TOPIC);
hszServerName = DdeCreateStringHandle(idInst,
szServerName,0);
// For the get details topic, get its string handle format
hszExecMacroTopic = DdeCreateStringHandle(idInst,
"DoExecMacro", NULL);
} // Hszize()
/* UnHszize -- This destroys often used global hszs from standard global strings.
*/
static void UnHszize(void)
{
DdeFreeStringHandle(idInst, hszServerName);
DdeFreeStringHandle(idInst, hszExecMacroTopic);
} // UnHszize()
/* DoDDERunMacro -- This routine starts a dde conversation with aruser and sends
its run macro command.
*/
VOID WINAPI DoDDERunMacro()
{
hConv = 0;
// Start the connection for run macro with the aruser server.
// NOTE: when we use NULL for the pCC parameter DDEMEL sends
// the default CONVECONTEXT.
while (TRUE) {
hConv = DdeConnect(idInst,hszServerName,
hszExecMacroTopic,NULL);
if (hConv)
break; // a connection was established
if (DdeGetLastError(idInst) != DMLERR_NO_CONV_ESTABLISHED)
break;
// Try again, maybe by now aruser is up and running.
} //while (TRUE)
if (hConv) {
// Build the a buffer that contains RunMacro function and
// send it to the aruser server
char szExecute[255];
Third-Party Applications and Macros ! 69
HDDEDATA hddeExecute;
// construct the data to be passed to the data
wsprintf(szExecute,"[RunMacro(%s,%s,%s=%s,%s=%s)]",
(LPSTR)"C:\\app\\macro", // the path where the macro is
(LPSTR)"SendMessage", // This is the name of the macro
// to run
(LPSTR)"Name",// This is the parameter name
(LPSTR)"John Smith", // This is the parameter value
(LPSTR)"Content",
// Parameter name
(LPSTR)"Don't forget about our meeting on Friday");
if (!(hddeExecute = DdeCreateDataHandle(idInst,
(LPVOID)szExecute,
lstrlen(szExecute)+1,0,NULL,CF_TEXT,NULL)))
; // give a memory allocation error message
else {
DdeClientTransaction((LPBYTE)hddeExecute, -1, hConv,
NULL,CF_TEXT, XTYP_EXECUTE, TIMEOUT_ASYNC, &XactID);
DdeFreeDataHandle(hddeExecute);
}
}//if (hConv)
else {
// failed to connect
}
} // end DoDDERunMacro()
The following examples show macro programs in Excel, Word, and Visual
Basic that run the SendMessage macro in AR System Windows User Tool.
The macros send a message to John Smith, reminding him of a meeting on
Friday. These sample programs assume AR System Windows User Tool is
running.
Excel Macro
Sub RunMacro()
Dim RunMacroString As String
RunMacroString = "[RunMacro(c:\app\macro,Send Message,Name=John
Smith,Contents=Don’t forget our meeting on Friday)]"
channelNumber = DDEInitiate("ARUSER-SERVER", "DoExecMacro")
DDEExecute channelNumber, RunMacroString
DDETerminate channelNumber
End Sub
Word Macro
Sub MAIN
RunMacroString$ = "[RunMacro(c:\app\macro,Send Message,Name=John
channelNumber = DDEInitiate("ARUSER-SERVER", "DoExecMacro")
DDEExecute channelNumber, RunMacroString$
DDETerminate channelNumber
End Sub
Visual Basic Macro
Private Sub cmdExecute_Click()
Dim RunMacroString As String
' Application|Topic
txtMacroPath.LinkTopic = "ARUSER-SERVER|DoExecMacro"
txtMacroPath.LinkMode = 2
RunMacroString = "[RunMacro("c:\app\macro,SendMessage,Name=John
txtMacroPath.LinkExecute RunMacroString 'send DDE message
End Sub
The DDE Active Link Action
DDE always takes place between a client application and a server application
on the same PC. The client initiates the exchange by establishing a
conversation with the server so that it can request data or services from the
server. The server responds by providing the data or services to the client. A
server can have many clients at the same time, and a client can request data
from multiple servers. Additionally, an application can be both a client and a
server. In AR System, AR System Windows User Tool is usually the client
application, and the DDE service is the server application. AR System
Windows User Tool can also be a DDE server.
The DDE Active Link Action ! 71
DDE uses a three-level hierarchy to uniquely identify a unit of data to be
exchanged during a DDE conversation:
Service Name
Identifies the DDE application with which AR System
Windows User Tool will establish a conversation.
Topic Name
Specifies the topic that identifies the logical data context.
Item Name
Specifies the location in the DDE application where you
will set a value.
For examples, see Active Link DDE Execute Action on page 75 and Active Link
DDE Poke Action on page 75.
Refer to the Microsoft Windows documentation for more information about
DDE.
Note: If you are designing an active link for a form that is also used by clients
on platforms other than a PC, verify that the current platform is a PC
as a condition of activating the DDE action. To do this, include a
qualification that uses the $HARDWARE$ keyword to verify the current
platform. See Developing AR System Applications: Basic guide for more
information on building qualifications.
Defining the DDE Active Link Action
With the Server Window open:
1 Select File > New Server Object
2 Select Active Link from the New Server Object field.
3 Click OK.
The Create Active Link dialog box appears.
4 Set up the conditions in the Basic tab.
6 From the New Action list, select DDE.
The fields required to define the DDE action appear. The following figure
shows these fields and an example of how a DDE (Execute) active link action
might look after you complete the remaining steps in this procedure.
Figure 3-1: DDE Active Link Action
7 From the Action option list, select a DDE action type.
Execute
AR System Windows User Tool request for the DDE application to
execute the command specified in the Command field.
Poke
AR System Windows User Tool request for DDE application to set
the value specified in the Command field to the location (for
example, a field or cell) specified in the Item field.
For more information on DDE execute and poke action types, refer to Active
Link DDE Execute Action on page 75.
8 In the Service Name field, enter the unique ID of the DDE application.
You can use the Service Name field menu button to insert fields from the
current form and append them to the service name.
9 In the Topic field, enter the DDE topic.
You can use the Topic field menu button to insert fields from the current
form.
10 In the Item field, enter the DDE item (if applicable).
The Item field is enabled only if the DDE Action type is Poke. You can use
the Item field menu button to insert fields from the current form.
11 In the Path field, enter the location of the service.
You can use the Path menu button to insert fields from the current form.
12 In the Command field, enter the command that you want to execute.
You must enter a value in this field. You can type the command or you can
build it using the Command list to insert fields from the current form and
keywords.
If the action is Execute, a command is sent to a DDE application. If the action
is Poke, data is set in the DDE application.
The DDE action appears in the Current Actions list.
See Assigning Values from a DDE Request (Active Links) in Developing AR
System Applications: Basic guide for information about loading the result of a
DDE request operation into a field by using an active link that performs a Set
Fields action.
Time-Out Settings for DDE Transactions
All AR System DDE transactions are synchronous. If you need to set longer
times for DDE transactions, you can create a [DDE] section in your ar.ini file
and enter your own time-out settings:
[DDE]
AppResponseTimeout=30
TransactionTimeout=20
AppResponseTimeout is the active link time-out setting to load the
application into memory after starting it. The default setting is 30 seconds.
TransactionTimeout is the active link time-out setting if the DDE server does
not respond to the requested DDE action. The default setting is 20 seconds.
Active Link DDE Execute Action
You can use the DDE Execute action to execute specific commands or
functions in a DDE application. The DDE application must be a Windows
application that supports DDE. The DDE Execute action requires the
following components:
Service Name
Application DDE name.
Topic
Additional DDE definition; for example, a file name or a
category of command (like the system command in Excel).
Path
Location of application executables. You must point the path to
the DDE application in the Service Name field.
Command
Command or function being sent to the DDE application.
For example, you can create an active link button that launches a Windows
application that supports DDE.
Active Link DDE Poke Action
You can use the DDE Poke action to send data to a DDE application. The
DDE application must be a Windows application that supports DDE. The
DDE Poke action requires all five of the following components:
Service Name
Application DDE name.
Topic
Additional DDE definition; for example, a file name or a
category of command (such as the system command in
Excel).
Item
Multiple items that identify the details in a topic; for example,
the cell location in a spreadsheet.
Path
Location of application executables. You must point the path
to the DDE application in the Service Name field.
Command
Data being sent to the DDE application. The data can be a
literal value or a data field value.
The following figure illustrates an active link that sends the value of the
Submitter field into cell R1C1 (row 1 and column 1) of Sheet1 in the Excel
spreadsheet application.
Figure 3-2: DDE Poke Action
Assigning Active Link Values Through DDE
Use active links to set a field to the value resulting from a DDE request
operation executed on a Windows client.
The syntax for loading the result of a DDE request operation is:
$DDE$ <service_name>;<topic>;<path_to_program>[;<item>]
The DDE parameters are defined as follows:
<service_name>
The unique ID of the DDE application.
<topic>
The topic name identifying a logical data context.
<path_to_program>
The location of the DDE service on the PC.
<item>
A string identifying a unit of data. This parameter is
optional.
For example, you might enter the following:
$DDE$ excel;sheet1;c:\excel\excel.exe;R1C1
This operation returns the contents of cell R1C1 of a file named sheet1 in
Microsoft Excel to the current field.
The keyword $DDE$ indicates that all following text is a DDE command line.
The command line can include substitution parameters from the current
screen to enable values from the current screen to be placed into the
command line before it is executed. You can select substitution parameters
(and the $DDE$ string) from the Fields Value list.
When the active link is performed on a Windows client, the specified DDE
request is executed and AR System Windows User Tool waits for the
operation to complete. The data returned by the DDE request is then entered
into the field.
If the active link is triggered by an action in a form on a non-Windows client,
an empty or null string is returned.
The following examples show AR System active links that use DDE to
integrate AR System with Microsoft Excel and Microsoft Word.
Microsoft Excel Example
The following example includes two active links that use DDE to integrate
Microsoft Excel with AR System. Using these active links, a user can open and
populate a spreadsheet in Microsoft Excel through an AR System form.
Assigning Active Link Values Through DDE ! 77
The following figure shows a sample form with active links that work with
Microsoft Excel. The two buttons on the left of the form activate the active
links that open and populate a spreadsheet. The active links reference the
fields to determine where Microsoft Excel is installed, which spreadsheet to
open, and what data to send to the spreadsheet.
Figure 3-3: Sample DDE Form
When the user clicks 1 Excel DDE Execute, the first active link is activated
and the specified spreadsheet is opened in Microsoft Excel. To create this
active link, the administrator uses the If Action tab of the Active Link dialog
box, as shown in Figure 3-4 on page 79.
Figure 3-4: Sample Active Link—1 Excel DDE Execute
!
The New Action field instructs the active link to execute a command.
!
The Path field references the Excel Program Location field in the sample
form to determine where Microsoft Excel is installed.
!
The Command field references the Command field in the sample form to
determine the specific action to perform.
The Command field in the sample form must have a value for this active link
to activate. The qualification is as follows:
'Command' != $NULL$
In the sample form, a user enters the location of the Microsoft Excel program
in the Excel Program Location field, a specific spreadsheet in the Spreadsheet
field, and an OPEN command in the Command field. You might want to
enable your users to populate these fields through active links or menu lists
to ensure that the syntax is correct.
As shown in The following figure, a user’s Microsoft Excel executable is
located at
c:\msoffice\excel\excel.exe. The particular spreadsheet to be opened is
located at c:\home\joeuser\exceldde.xls. The OPEN command in the
Command field opens the spreadsheet.
Figure 3-5: Sample DDE Form with Sample Data
When the user clicks 1 Excel DDE Execute, Microsoft Excel opens and
displays the exceldde.xls spreadsheet.
When the user clicks 1 Excel DDE Poke, the second active link is activated
and a specified spreadsheet is populated. To create this active link, the
administrator uses the If Action tab of the Active Link dialog box, as shown
in Figure 3-6 on page 81.
Figure 3-6: Sample Active Link—1 Excel DDE Poke
!
The Action field instructs the active link to send data to some location.
!
The Item field indicates the item to which data will be poked.
!
The Path field references the Excel Program Location field in the sample
form to determine where Microsoft Excel is installed.
!
The Command field references the Poke Data 1 field in the sample form
to determine the data to send to cell R1C1 in the spreadsheet.
The Excel Program Location, Spreadsheet, and Poke Data 1 fields in the
sample form must all have values for this active link to activate. The
qualification is as follows:
(('Excel Program Location' != $NULL$ ) AND
('Spreadsheet' != $NULL$ )) AND ('Poke Data 1' != $NULL$ )
There are three actions for this sample active link—one each to poke data
from the three poke fields to three cells in a spreadsheet.
When a user supplies data to the three Poke Data fields in the sample form
and clicks 1 Excel DDE Poke, the data in the Poke Data fields are sent to cells
in the spreadsheet specified in the Spreadsheet field.
Microsoft Word Example
The following example includes two active links that use DDE to integrate
Microsoft Word with AR System. Using these active links, a user can open
and write to a document in Microsoft Word through an AR System form.
The following figure shows a sample form having active links that work with
Microsoft Word. The two buttons on the left of the form activate the active
links that open Microsoft Word and write to a document. The active links
reference the fields to determine where Microsoft Word is installed, which
document to open, and what data to send to that document.
Figure 3-7: Sample DDE Form
When the user clicks 1 Word DDE Execute, the first active link is activated,
and a specified document is opened in Microsoft Word. To create this active
link, the administrator uses the If Action tab of the active link dialog box, as
shown in Figure 3-8 on page 83.
Figure 3-8: Sample Active Link—1 Word DDE Execute
!
The Action field instructs the active link to execute a command.
!
The Path field references the Word Program Location field in the sample
form to determine where Microsoft Word is installed.
!
The Command field references the Command field in the sample form to
determine the specific action to perform.
The Command field in the sample form must have a value for this active link
to activate. The qualification is as follows:
'Command' != $NULL$
In the sample form, a user enters the location of the Microsoft Word
program in the Word Program Location field, a specific document in the
Document field, and an OPEN command in the Command field. You might
want to enable your users to populate these fields through active links or
menu lists to ensure that the syntax is correct.
As shown in the following figure, a user’s Microsoft Word executable is
located at
c:\msoffice\winword\winword.exe. The particular document to be opened
is located at c:\home\joeuser\arsdde.doc. This document will be opened by
the OPEN command in the Command field.
Figure 3-9: Sample DDE Form with Sample Data
When the user clicks 1 Word DDE Execute, Microsoft Word opens and
displays the arsdde.doc document.
When the user clicks 1 Word DDE Poke, the second active link is activated
and writes to a specified document. To create this active link, the
administrator uses the If Action tab of the active link dialog box, as shown in
the following figure.
Figure 3-10: Sample Active Link—1 Word DDE Poke
!
The Action field instructs the active link to send data to some location.
!
The Item field indicates the item to which data will be poked.
!
The Path field references the Word Program Location field in the sample
form to determine where Microsoft Word is installed.
!
The Command field references the DDE Poke field in the sample form to
determine the data to send to bookmark 1 in the document.
The Word Program Location, Document, and DDE Poke fields in the sample
form must all have values for this active link to activate. The qualification is
as follows:
(('Word Program Location' != $NULL$ ) AND
('Document' != $NULL$ )) AND ('DDE Poke' != $NULL$ )
When a user supplies data to the DDE Poke field in the sample form and
clicks 1 Word DDE Poke, the data in the DDE Poke field is sent to the
document specified in the Document field.
DDE and Reports
You can create a report to send to another installed application by using
DDE.
Sending a Report to Another Windows Application
Before you can send a report to another application, perform the following
procedure:
1 Choose Tools > Options in AR System Windows User Tool.
2 Click the Reports tab.
3 Select the Enable Report to Applications check box.
4 Click OK.
Specifying Report Information in the dde.ini File
1 Open or create the dde.ini file.
The dde.ini file can be found in your configuration directory (\Home by
default). It can be set up for use with multiple applications and is similar to
other Windows .ini files. If you do not have a dde.ini file, create one and
include the appropriate information shown below.
2 Using a text editor, specify the fields that are required for DDE in the dde.ini
file as follows:
Path
Specifies the full path of the application. Because this value is
used to start the application, specify any required parameters
in this field along with the path, for example:
Path = c:\excel\excel.exe
Application
Specifies the name of the application. Use the DDE server
name of this application, for example:
Application = excel
Topic
Specifies a series of DDE topics for each application. For
more information, see the application’s DDE
documentation. For example:
Topic = system
Format
Specifies the column separator character. The options are
Tab, CSV, Record, or Current Format. For example:
Format = Tab
This takes precedence over any column-separator character
that you have specified in the Report Preferences, Page
Setup, or Report Options dialog box.
Tab format displays the report with column values separated
by tabs. Depending on the application displaying the report,
data may not align correctly.
CSV format forces the application to display the report in
rows, with column values separated by
commas.
Record format displays the report in record format. All the
page setup information is reset. You can also specify an
optional parameter CharsPerLine. If CharsPerLine is not
specified, the default is 80.
Current Format uses the format and page setup defined in
the application.
XFRDATA
Specifies how the other application needs to receive the
report. Enter either Clipboard or File, for example:
XFRDATA = Clipboard
For more information, see the application’s DDE
documentation.
Command
Specifies commands that an application requires. You can
enter as many commands as needed by using the fields
Command1 through Command<n>, but they must be
sequential, for example:
Command1 = [NEW(1)] [PASTE( )] [SAVE.AS(,0)]
Because reports are always written to a temporary file, you
can specify the path of this temporary file on the command
line. To do this, use the %f and %N parameters. If you specify
%f, AR System replaces the parameter with the path of the file
containing the report. If you specify %N, AR System replaces
the parameter with the name of the file containing the report.
For more information, see the application’s DDE
documentation.
The following example illustrates a dde.ini file that sends a report to
Microsoft Excel by using the clipboard:
DDE and Reports ! 87
[excelclipboard]
Path=c:\excel\excel.exe
Application=excel
Topic=system
Format=Tab
XFRDATA=Clipboard
Command1=[NEW(1)] [PASTE()] [SAVE.AS(,0)]
[excelfile]
Path=c:\excel\excel.exe
Application=excel
Topic=system
Format=Tab
XFRDATA=FILE
Command1=[OPEN("%f")]
Microsoft Word by using the clipboard:
[wordrecord]
Path=c:\msoffice\winword\winword.exe
Application=winword
Topic=system
Format=Record
CharsPerLine=100
XFRDATA=Clipboard
Command1=[FileNew .Template = "Normal", .NewTemplate = 0]
Command2=[Editpaste]
Microsoft Word in the Current Format by using a file:
[WordCurrFormatFile]
Path=c:\msoffice\winword\winword.exe
Application=winword
Topic=system
Format=CurrentFormat
XFRDATA=File
Command1=[FileOpen .Name="%f"]
Note: When sending a report to another application by using DDE, the
report preferences, page setup, and report options are ignored. For
example, if you specified a column separator character, it is ignored
and the value in the Format field in the dde.ini file is used instead.
4
Using Full Text Search
CHAPTER
This chapter discusses the capabilities, performance, and
administration of the full text search (FTS) feature. The following
topics are covered:
!
What Is Full Text Search? on page 90
!
Who Can Perform a Full Text Search? on page 94
!
Using FTS on page 94
!
Administering FTS on page 102
!
Assigning FTS Licenses to Users on page 106
!
Defining a Field for FTS in the Field Properties Window on page 107
Note: Full text search is an optional feature that you can purchase for the AR
System server.
Using Full Text Search ! 89
What Is Full Text Search?
Full text search (FTS) is an important and useful feature of AR System. FTS
is typically much faster than searching in relational databases for long text
fields.
A benefit of FTS is that you can use of your knowledge base. For example,
FTS enables you to access your company’s history of solving problems, which
are sometimes stored in long text fields. With the FTS option, you can easily
search through long text fields to find solutions to related problems. You
might even want to redesign forms to require users to enter data into diary or
long text fields. You can then build up a knowledge base that helps you learn
from previous experience.
FTS provides quick and consistent access to AR System requests for which
you are searching. The FTS accrue operator presents the best solutions to
your search first by using a weighted order. The accrue operator enables you
to use multiple search terms in a search; for example, computer, PC, and error
number 3794. Requests that contain the most search terms appear higher on
the list (if ordered in descending order of weight) and are more likely to
contain the information for which you are looking. In contrast, if an OR
search yielded 20 requests, you must look through all 20 requests because you
would not know which requests contain what information. For more
information, see Accruing and Weighting Results with FTS on page 92.
FTS solves many problems that users encounter when performing database
searches, including:
!
Searching long text fields. The FTS option enables you to index character
and diary fields for searching, and then matches entries from those fields
against the search criteria you specify. Like database indexes, an FTS index
can greatly decrease the time required for a database search.
!
Improving search performance by searching large volumes of data. FTS
organizes text in a way that typically provides quicker access than
relational databases.
!
Defining how the server interprets wildcards to customize search
performance to your specific needs. For more information about
configuring FTS options, refer to the Configuring AR System guide.
!
Performing case-insensitive searches. Administrators can enable or
disable case sensitivity. For more information about configuring FTS
options, refer to the Configuring AR System guide.
90 "Chapter 4—Using Full Text Search
!
Using bracket ([]) wildcards in an FTS field, even if the underlying
database does not support them. For example, you could enter do[a-z] to
find requests that include doe, don, and dot.
FTS Functionality from Verity
The FTS features in AR System are based on technology from the Verity
Developer’s Kit (VDK) from Verity, Inc. The following sections discuss how
the FTS features from Verity are implemented in AR System.
Free Text Search
AR System’s use of VDK was prior to free text search being available from
Verity. Accordingly, free text searching is not implemented in this version of
AR System.
Thesaurus
This functionality is not implemented in this version of AR System.
Hankaku Katakana and Zenkaku Katakana Searches
AR System performs Hankaku (single-byte) Katakana and Zenkaku
(double-byte) Katakana alphanumeric searches according to the rules of the
Verity technology. The case-sensitive feature of AR System is ignored during
these searches.
Operator Matrix
The table that follows outlines which operators from the Verity technology
have been implemented in AR System.
Table 4-2: Operator Matrix (Sheet 1 of 2)
Operator Name
Implemented in AR System
Word
No
Stem
Yes
Thesaurus
No
Wildcard
Yes
Soundex
No
In
No
Phrase
Yes
What Is Full Text Search? ! 91
Table 4-2: Operator Matrix (Sheet 2 of 2)
Operator Name
Sentence
No
Paragraph
No
Near
No
Near/n
No
Contains
No
Matches
Yes
Starts
Yes
Ends
No
Substring
No
And
No
Or
No
Accrue
Yes
Modifier Matrix
The following table outlines which modifiers from the Verity technology
have been implemented in AR System.
Table 4-3: Modifier Matrix
Modifier
Case
Yes
Many
Yes
Not
Yes
Order
No
Accruing and Weighting Results with FTS
Weighting the results of an accrue search is a powerful FTS feature. FTS does
not limit you to searches for keywords in fields indexed for FTS. You also can
use a special accrue operator (the LIKE operator with comma-separated
words, for example) to cause AR System to accrue and retrieve from the
database all requests that contain any or all of the comma-separated words.
For more information, see Using the Accrue Operator on page 97.
Requests that are retrieved in an accrue operation are assigned a weight by
the FTS engine. Weight is a number that varies from 0 to 100. With weight,
AR System can sort requests in a results list using a “the more, the better”
approach. If you set the Field Sort Order in AR System Windows User Tool
to include weight in descending order, the more search terms found in a
request, the higher in the list it appears in the set of retrieved requests. The
closer Weight is to 100, the better it matches the search criteria.
For more information about modifying results list attributes to include FTS
weights, see Displaying FTS Weight in a Results List on page 109.
Sorting Requests by Weight
In AR System Windows User Tool, users can sort the requests that are
retrieved by FTS by weight in descending or ascending order by selecting
Weight and the sort order in the Field Sort Order window. For more
information about setting the sort order, see AR System Windows User Tool
help.
Using the Ignore Words List
You can configure the FTS engine to ignore frequently used words (such as
and, the, because, and so on) or words that you do not want indexed. Adding
entries to the Ignore Words List saves space in the FTS index and speeds up
text searches. The FTS option comes with a default set of ignored words that
you can modify as needed. For information about modifying the ignore
words list, refer to the Configuring AR System guide.
Accrue searches that contain words from the Ignore Words List do not find
any matching AR System requests for those words. However, the accrue
search retrieves requests for the other search terms. For restrictions on FTS,
see Limitations of FTS on page 101.
Note: The Ignore Words List is different for each supported language.
What Is Full Text Search? ! 93
Who Can Perform a Full Text Search?
Users must have a fixed or floating FTS license to use the FTS capability. FTS
licenses are separate from AR System read/write licenses.
!
If users are assigned a fixed FTS license, they can always perform a search
in a field indexed for FTS.
!
If users are assigned a floating FTS license but one is not currently
available, they receive a warning the first time they perform a database
operation in AR System Windows User Tool. The system uses the search
capabilities of the underlying database (to the degree available). When a
floating license becomes available, an affected user is alerted with a note
and can perform a search by using the FTS capability.
For more information about who can use Full Text Search, see Assigning FTS
Licenses to Users on page 106.
Using FTS
FTS is transparent to users who have an FTS license (fixed or floating).
!
If an FTS license is available and the field is indexed for FTS, then FTS is
used.
!
If an FTS license is unavailable or the field is not indexed for FTS, AR
System uses the search capability of the underlying database.
Users enter search criteria in the same way, whether they are using FTS or
not.
Performing a Search in a Field Indexed for FTS
In most cases, entering a string into a field indexed for FTS returns results
consistent with the ordinary database searches most users expect. Users can
still use the search strings and search patterns with which they are already
familiar. FTS offers additional benefits. Unlike some databases, the FTS
engine enables you to index and search text fields for any words in the entire
field. Users might also notice enhanced performance in retrieving AR System
requests.
The search method used by the FTS engine depends on the following factors:
!
The original search criteria as entered by the user
!
The QBE match settings of the field
!
The FTS Search Options setting of the server
FTS uses these factors to determine the final search criteria. Succeeding
factors override preceding factors. For example, if a user includes a leading
wildcard as part of a full text search, but the FTS Search Options setting is set
to Ignore Leading Wild Card, FTS ignores the wildcard entered by the user.
See How QBE Settings Affect FTS on page 100 for more information.
The FTS engine uses the final search criteria to search the contents of all
requests indexed for that field, and it uses one of three search methods:
!
Accrue searches
!
Phrase searches
!
Character searches
Note: All the following examples use FTS in the Advanced Search Bar, not
QBE. They also assume that the FTS Search Option is set to Query
Unchanged. For more information about configuring FTS options,
refer to the Configuring AR System guide.
Accrue Searches
During an accrue (OR) search, the FTS engine finds requests that contain any
of the specified words in a field, instead of matching a string of characters.
The FTS engine matches the pattern of the characters specified in the search.
For example, consider the following accrue search:
<field> LIKE "hello, world, greetings"
The search criteria returns requests with any of the three words. You cannot
use an accrue search to search for punctuation or other special characters.
For more information about using an accrue search, see Using the Accrue
Operator on page 97.
Phrase Searches
During a phrase (word) search, the FTS engine finds requests that contain the
specified words in the field, instead of matching a string of characters. To
perform a phrase search, use double-quotation marks around the words you
want to search for and use leading and trailing wildcards, as in the following
example:
Using FTS ! 95
<field> LIKE "%<word_to_be_searched_for>%"
For example, if you want to look for the word “hello,” type:
<field> LIKE "%hello%"
The search criteria "%hello%" returns requests with hello world and hello,
world. You cannot use a phrase search to search for punctuation or other
special characters.
A phrase search is especially useful for finding embedded words that are not
word stems. If your phrase search includes the word cat, it also finds the
words housecat and catatonic.
See FTS Issues When Performing Searches on page 99 for more information.
Character Searches
Unlike accrue or phrase searches (which are word-based), the FTS engine
uses a character search to find requests that match the string of characters
based on the contents of the entire field. To perform a character search, use
double-quotation marks around the words you want to search for, as in the
following example:
<field> LIKE "<word_to_be_searched_for>"
For example, consider the following character search:
<field> LIKE "world"
The search criteria returns only those requests that contain exactly the
character string world in the field. If the field contains hello world, a character
search does not return this request. However, you can add either a leading
wildcard or a trailing wildcard to increase the scope of a character search. (If
you use both a leading and a trailing wildcard, you are no longer using a
character search; you are using a phrase search instead.) For example,
consider this search with a leading wildcard:
<field> LIKE "%world"
The search criteria %world returns requests with world at the end of the field,
such as hello world or a small world. If you add a trailing wildcard to the
search criteria, as <field> LIKE "world%", the search criteria returns requests
with world at the beginning of the field, such as world without end. But you
will not find a request with a field that begins with hello world.
See FTS Issues When Performing Searches on page 99 for more information.
Using the Accrue Operator
You can use a special accrue operator (the LIKE operator with comma
separators) to search for requests with multiple terms, as the following entry
in a field indexed for FTS:
left, right, turn
This search retrieves all requests with any of the search terms and their stems.
You also can perform an accrue search for a single word, as in the following:
turn,
When the FTS engine encounters a comma in the search string, it uses the
accrue operator, even if there is only one search term. This search retrieves
requests with turn and its stems. For information about stems, see Searching
for Word Stems on page 98.
Note: You can use the accrue operator only with fields indexed for FTS.
Using the same operator for a field that is not indexed for FTS causes
the AR System server to search for the literal string.
Using the QBE Method
!
!
If the QBE Match property for the field is not set to Equal, you do not need
to add any wildcards to the search string, as in the following:
left, right, turn
If the QBE Match property for the field is set to Equal, you must add a
leading wildcard to the string to use the accrue operator, as in the
following:
%left, right
For more information about how QBE settings affect FTS, see How QBE
Settings Affect FTS on page 100.
Using FTS ! 97
Using the Advanced Search Bar Method
Use the accrue operator in the Advanced Search Bar, according to the
following syntax:
<field> LIKE "left, right"
The accrue operator causes AR System to retrieve requests that contain one
or more of the search terms left or right. A full text search also returns weight
information about the number of occurrences found.
Searching for Word Stems
For case-insensitive searches with no wildcards added, you can use the accrue
operator to search for common variations of word stems. For example, the
search left, right, turn in a field indexed for FTS also retrieves requests with
the following variations of turn:
!
turns
!
turned
!
turning
This also applies to nonaccrue word searches having both a leading and
trailing wildcard. For example, a search for %someone turns around% returns
requests containing:
!
someone turns around
!
someone turned around
!
someone turning around
However, the capability of searching for word stems does not match requests
with turnabout, return, or upturn in them as variations of turn.
Using Wildcards
You can also use the percent sign (%) wildcard for a search with the accrue
operator, according to the following syntax:
<field> LIKE "left%, right"
This search retrieves all requests that contain the search term right and words
that start with left, such as leftover.
Combining FTS and Non-FTS Fields
You can include FTS and non-FTS fields in a search, as in the following:
<field> LIKE "left, right" AND 'Create Date' > "01/01/99"
This Advanced Search Bar search with the FTS accrue operator returns all AR
System requests that contain any of the search terms left or right and were
created after January 1, 1999. For efficient searches with better performance,
group all FTS fields at the beginning of complex search expressions.
Search Strategies and Issues
When searching fields for which FTS indexing is enabled, be aware of the
following tips and strategies:
!
Make your searches as specific as possible. The more defined and qualified
your searches are, the less the database is impacted. Also, you might find
the information that you want more easily (instead of having to search
through hundreds of requests). A more efficient search gives a quicker
response time.
!
Group FTS fields at the beginning of complex search expressions.
!
Remove common words from full text searches. Use specific, particular
search terms. For example, if you use the accrue operator against five
words and the search yields hundreds of requests, delete the most generic
terms from the criteria to focus your search on a smaller set.
Some searches work better than others. If you receive unexpected results or
a time-out, rewrite your search.
FTS Issues When Performing Searches
Be aware of the following issues when performing full text searches:
!
Full text searches that involve a field reference to the right of the relational
operator are not supported. A warning message occurs which indicates
that the query was treated as a database query instead of an FTS query. The
presence of ‘Assigned To’ in the following example returns the warning
message if the Short Description field is indexed for FTS:
'Short Description' LIKE 'Assigned To' + "ing"
If there are no variables to the right of LIKE in the statement, FTS handles
the search. For example:
'Short Description' LIKE "work" + "ing"
Using FTS ! 99
In this example, the search is handled by FTS because the two known
values (work and ing) are combined to form one known value (working).
!
FTS does not treat some characters as literal characters in a search string
unless they are preceded by a backwards slash. The following characters
have unique functions in a full text search:
!
braces ({})
!
brackets ([])
!
backslash (\)
Note: These characters and the majority of other nonalphanumeric
characters can only be included in a pattern search. They cannot be
used at all (with or without backward slashes) in word searches
because these characters are not defined as characters that combine
with other characters to form words.
How QBE Settings Affect FTS
Enter a query by example (QBE) in any field indexed for FTS, according to
the following syntax:
left, right
However, be aware that the property settings influence how an accrue search
works, as shown in the following table.
Table 4-4: How QBE Property Settings Affect FTS (Sheet 1 of 2)
QBE Match Property Setting
Effect on Search Criteria
Anywhere
%left, right%
AR System Windows User Tool adds wildcards
to the start and end of the search.
Table 4-4: How QBE Property Settings Affect FTS (Sheet 2 of 2)
QBE Match Property Setting
Effect on Search Criteria
Leading
left, right%
AR System Windows User Tool adds a wildcard
to the end of the search.
Equal
left, right
AR System Windows User Tool does not add
any wildcards to the search string, but it uses the
EQUAL (=) operator instead of the LIKE
operator if the first character in the search string
is not a percent sign (%).
Therefore, to use the accrue operator with a
QBE Match setting of Equal, users can do one of
the following:
! Add a leading wildcard to the string, as
follows:
!
%left, right
!
Use the Advanced Search Bar to enter the
accrue operator.
Note: When you index a field for FTS by using the Database tab of the Field
Properties dialog box, do not set the QBE Match property to Equal.
For more information on QBE, see the Developing AR System
Limitations of FTS
Limits to performing a full text search include the following:
!
In accrue searches, you cannot search for most punctuation marks
because they are treated as word separators. For more detail, see FTS Issues
When Performing Searches on page 99.
!
In accrue searches, do not use words from the Ignore Words List. For
example, if the word the is in the Ignore Words List, searching on the
phrase the, database, request in the Short Description field might return
requests with the word the in them, but it is not used in the search itself.
For additional information about the Ignore Words List, refer to the
Configuring AR System guide.
Using FTS ! 101
!
In searches that use FTS, submitted or modified requests might not appear
immediately in the results list if you are searching on a field enabled for
FTS. There is sometimes a short delay from the time the request is
submitted or modified in the database to the time that the request is
available for searching in the FTS index.
!
On a server running in the English locale, words can contain only the
following characters, if they are to be indexed under FTS:
_ABCDEFGHIJKLMNOPQRS
TUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$%#@.
!
On a server running a locale of other Western European languages in the
ISO 8859-1 character set, words can contain only the following characters,
if they are to be indexed under FTS:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghij
klmnopqrstuvwxyzäöüßÄÖÜåÅ>>øØàÀáÁâÂèÈéÉëËêÊìÌíÍïÏîÎòÒóÓùÙ
úÚñÑûÛçÇôÔýÝðÐãÃõÕÞþ0123456789$%#@.
Administering FTS
This section describes how to administer FTS in AR System.
Selecting Fields for FTS Indexing
You can only index character or diary fields for FTS. Index only fields that are
frequently searched, such as work diaries and descriptions of problems,
especially if the underlying database does not support searches of these fields.
For example, you could perform a search for one or more keywords in a diary
field that would retrieve and weight all AR System requests that describe how
to solve a problem suggested by those keywords. You would perform a search
on keywords or phrases such as the following:
!
Forms, tools, screens, and hardware and software products
!
Descriptions of problems or solutions
!
Other areas of interest
When you define a field as indexed for FTS, it might take some time before
that field is available for Full Text Search. Indexing a field can take up to
several hours, depending on the amount of data in that field, the system load,
and other factors. While a field is being indexed for FTS, you can still do
non-FTS searches on that field if the underlying relational database permits
it. To index a field for FTS, see Defining a Field for FTS in the Field Properties
Window on page 107.
For each field that you index for FTS, the amount of disk space required for
the FTS index can grow significantly. To estimate approximately how much
space is required for your FTS index, see Estimating the Size of the FTS Index
on page 108.
Do not define fields for FTS during normal production hours, especially if
you have many AR System requests in your database. The indexer accesses
the database at the same time as the AR System servers, which can
significantly impact the performance of your system.
Reindexing
Most of the time, you should not have to rebuild your FTS index because the
arservftd (arfts.exe) process automatically optimizes space after AR System
requests are added or deleted. However, you might need to rebuild the FTS
index (reindex) if you make changes to your Ignore Words List. For
additional information about rebuilding the full text search index, refer to
the Configuring AR System guide.
Time Required to Rebuild an Index
Do not rebuild an index during normal production hours. Because
reindexing rebuilds your entire FTS index from scratch, it can take a long
time, depending on the following factors:
!
The amount of data in each field indexed for FTS in each AR System
request
!
The system load
!
Whether your indexes are on NFS-mounted or local directories
For more information about locating your FTS indexes, see Estimating the
Size of the FTS Index on page 108.
Administering FTS ! 103
After Modifying the Ignore Words List
When you modify the Ignore Words List and do not reindex, your changes
affect only entries that are inserted, deleted, or modified after that time. For
example, if you added network to the Ignore Words List, the FTS index
ignores the word network only for AR System requests added or modified
from this time forward. However, the FTS index with the word network
would still exist for all requests created before the Ignore Words List was
modified.
When you reindex all the fields in all your forms that are currently flagged as
indexed for FTS, you create a new FTS index that then ignores the word
network in all requests. To change the Ignore Words List, refer to the
The FTS Server (arservftd) Process
AR System uses the arservftd process (arfts.exe on Windows) to insert or
delete data in the FTS index. All changes to the FTS index are made through
the arservftd process. In addition, the arservftd process optimizes the FTS
index every 2000 index field commands (from the time that arservftd is
started), removing spaces added during modify and delete operations. The
optimization enables the index to run more efficiently.
AR System runs only one arservftd process at a time. The arservftd process
is started or stopped by the arserverd process if you have valid FTS user
licenses.
When you are performing a full text search, the arserverd process searches
the FTS index for AR System requests. If the server’s FTS operations are
disabled when a request is submitted, modified, or deleted, changes are still
preserved for later inclusion in the FTS index. When changes are made, they
are recorded in the arftp.lst file. If FTS operations are enabled, those changes
are processed and included in the FTS index.
Note: If FTS operations are disabled while the FTS indexer process is
processing a change, that processing will complete before the indexer
process is disabled. Some operations, like indexing an entire field for
the first time, can take a long time depending on how many entries
exist. These operations are considered a single unit of work and will
not be interrupted when FTS operations are disabled.
Debugging FTS
All debug tracing for FTS is logged in the <ar_install_dir>/db/arft.log file.
Enabling FTS Debugging
1 Add the following line to your configuration file:
FTS-Debug-mode: 15
A value of 15 logs all activity in the indexer process. You also can specify any
combination of the following trace options for more selective logging:
!
1 for VDK failures
!
2 for incoming index commands
!
4 for index drop commands
8 for VDK commands
If any of the above trace options are selected, VDK internal logging is
performed and logged in the <ar_install_dir>/db/arftext.log file.
Note: VDK internal logging is very intensive and time consuming. See the
following bullet for an additional trace option you can select to turn
off this logging while performing the indexer process logging.
!
!
128 for the elimination of VDK internal logging
To perform all types of indexer process logging without VDK internal
logging, add the following line to your configuration file:
FTS-Debug-mode: 143
The 143 trace option consists of 128 (elimination of VDK internal
logging) plus 15 (logging all activity in the indexer process).
2 On UNIX, use the ps command to get the process ID of the arservftd process.
3 On UNIX, stop the arservftd process by typing the following:
kill -15 <process_number_arservftd>
The arserverd process automatically restarts the arservftd process and begins
logging immediately.
On Windows, stop and restart the server as described in the Installing AR
System guide.
Administering FTS ! 105
Assigning FTS Licenses to Users
To perform a full text search, users must be assigned a fixed or floating FTS
license. You specify the type of license that users have through their request
in the User form (Figure 4-1 on page 106), as you would with their AR
System write licenses.
Licensing a User for FTS
1 Open the User form in AR System Windows User Tool.
2 Search the database for the user who you want to license for FTS and open a
window.
Figure 4-1: User Form
3 Select the Full Text License Type option for the type of FTS license that you
want the user to have, whether fixed or floating.
4 Click Save.
If you issued the user a fixed FTS license, a confirmation message appears.
5 Click OK to dismiss the message.
Defining a Field for FTS in the Field Properties Window
Use the Field Properties window to create an FTS index of text in character
and diary fields. Do not define fields for FTS during normal production
hours, especially if you have many AR System requests in your database.
Defining a Field for FTS
1 Open the Field Properties window.
2 Click the Database tab.
The Database section appears, as shown in the following figure.
Figure 4-2: Database Tab in the Field Properties Window
3 Select the Index For FTS check box.
4 Save your changes.
AR System begins to index the field for FTS.
The FTS index for a field is automatically updated and does not require
manual administration when you create, delete, or modify requests.
Note: The Index For FTS check box does not appear for servers that are not
licensed for the FTS option.
Defining a Field for FTS in the Field Properties Window ! 107
Estimating the Size of the FTS Index
Place the FTS index in a directory that has sufficient disk space. The directory
must be large enough to accommodate at least two times the amount of data
that is indexed for FTS. For example, if the total amount of data in all fields
you want to be indexed for FTS in all forms is 100 MB, then at least 200 MB
of disk space is required for the indexes. This example of determining the size
of an FTS index is an approximation only.
Estimating the Size of the FTS Index
Use this procedure to determine approximately how much disk space is
occupied by the FTS index.
1 Estimate the size of text in your database.
For example, take a small sample of requests and calculate the average size of
data in the field. Then multiply this average by the number of AR System
requests to derive the size of text in your database.
2 Use a minimum number of 2 as a multiplier.
The ratio of the size of the FTS index to source text can differ widely based
on, for example, the size of your Ignore Words List.
If the estimated size of text is 100 MB, the FTS index occupies at least 200 MB
of disk space: 100 MB * 2.0 = 200 MB as the lower boundary of the FTS index
and 100 MB * 2.5 = 250 MB as the upper boundary.
3 Consider the additional disk space needed during optimization.
When the indexer process optimizes the FTS index (see The FTS Server
(arservftd) Process on page 104), up to twice the normal disk space is used on
a temporary basis while the new optimized index is being built and the
existing index files are still present. After a migration period, the old index
files are removed.
Moving the FTS Index
In some situations, you may need to move the FTS index, especially if it
becomes quite large. You can choose to move the index manually and then
specify the new location in AR System Administrator, or you can move the
index by rebuilding the index at the new location. Create indexes on local
partitions in your system, not NFS-mounted partitions. Indexing and
searching NFS-mounted directories takes significantly longer than local
directories. Refer to the Configuring AR System guide for information about
rebuilding the FTS index at a new location.
The installation script for AR System places the FTS index into the
<ar_install_dir>/ftindex directory by default. If you have a large amount of
data indexed for FTS, you might find that you need more disk space in which
to place the FTS index. Use AR System Administrator to disable FTS
operations, and then move the index as needed. For more information about
configuring FTS, refer to the Configuring AR System guide.
If you decide to move the FTS indexes, relocate them to a directory with
enough space. To estimate the size of FTS indexes, see Estimating the Size of
the FTS Index on page 108.
Moving the FTS Index Manually
1 Estimate how much space you need in the new directory location.
2 Ensure that the number of pending AR System requests in the
3
4
5
6
7
8
<ar_install_dir>/db/arftp.lst file reaches 0.
Open the Server Information dialog box, and disable FTS by clearing the
Enable Full Text Search check box.
Click Apply.
Type the new location of the index in the FTS Index Directory field.
The server moves the index to the new location.
Click Apply to begin the move.
Select the Enable Full Text Search check box.
Click OK.
Displaying FTS Weight in a Results List
In the Results List Fields tab of the Form Properties dialog box, you can
configure results lists to display the FTS weight for all requests retrieved.
Displaying FTS Weight in a Results List
1 In AR System Administrator, open the form for which you want to define the
results list format.
2 Choose Form > Form Properties.
The Form Properties dialog box appears, as shown in Figure 4-3 on page 110.
Defining a Field for FTS in the Field Properties Window ! 109
Figure 4-3: Results List Fields Tab
3 Click the Results List Fields tab.
4 From the Fields in Form list, select WEIGHT.
5 If necessary, specify a Separator and Width.
6 Click Add.
7 Click OK to save your results list definition.
The Weight field displays the weighted value of retrieved AR System requests
when you create a results list in AR System Windows User Tool. The requests
are listed in descending order, based on how many times the search terms
were found.
8 Save the form.
If your search does not use the accrue operator, all requests returned in the
list are given the same weight value. For more information, see Sorting
Requests by Weight on page 93.
5
Localizing AR System Applications
CHAPTER
AR System provides a global product solution, not just a product
optimized for a single language or locale. Language, and thus
localization, is an integral part of the product, rather than a separate
language-specific product version.
You can localize components of AR System, allowing users to
seamlessly move between locale-specific views by simply changing
their locale option and logging in.
This chapter summarizes the areas of AR System related to the task of
creating localized AR System applications.
!
Localizing AR System Forms and Applications on page 112
!
Selecting Languages During Installation of AR System on page 117
!
Creating a Localized View of a Form on page 119
!
Localizing the User Interface of a Form View on page 120
!
Localizing Message Components of a Form View on page 124
!
Localizing Menus on page 131
!
Localizing Currency Types on page 134
!
Localizing the Mid Tier on page 134
!
Settings and Procedures for the Localized Environment on page 135
Localizing AR System Applications ! 111
Localizing AR System Forms and Applications
AR System can recognize and react to the locale of the user, and produce all
formatting and messaging that reflects the user’s language, customs, and
culture. Any AR System component that a user interacts with can be
localized, including:
!
User interface
!
Error messages
!
Workflow messages
!
Banners
!
Container labels and descriptions
!
Help text
!
Layout
!
Icons
!
Reports
!
Number and date formats
Getting Started
Localization begins with decisions made during installation. AR System has
the option of installing multiple language forms and dll’s on to a single client
machine, enabling users to seamlessly move between languages by simply
changing the preferred locale setting.
You can enable a localized environment with a single option in AR System
Administrator as described in Localize Server Setting on page 135. Working in
an enabled localized environment adds some extra processing time, but the
benefit of managing a multi-language version of AR System on a single client
platform exceeds the minor performance overhead.
Structure and Design
Administrators define the structure of the localized environment, but users
decide the language in which they want to view and process data. Users set
the locale preference that drives the selection process when looking for
localized AR System components. Users define their locale by the language
they speak, and the country where that language is spoken. AR System
components are localized by associating them with a specific locale.
112 "Chapter 5—Localizing AR System Applications
As the architect of a localized environment, you can create locale-specific
views of forms to accommodate the preferred locale of your users. Users will
generally log in specifying their <language_country> preference, but, when
defining the locale for a form view (or any AR System component),
administrators have the option of defining only the <language> portion of
the variable. This design allows users to log in with their <language_country>
preference, for example, fr_CA (French Canadian), but only a single form
view is needed with a fr locale specified to accommodate all French-speaking
countries. A localized view of a form is accessed through a browser by
specifying the preferred locale in a URL (see the information about opening
forms in a browser in the Developing AR System Applications: Basic guide.
AR System is designed with a fallback lookup mechanism when searching for
a view to display to users. This enables AR System to always find a view to
open, even when the user does not specify a preferred locale. For more
information about the fallback lookup mechanism, see Creating a Localized
View of a Form on page 119. For more information about how a view is
selected for the user, refer to the Developing AR System Applications: Basic
guide.
Localizing Form Views
After a form view is defined for a specific locale, features throughout AR
System are then used to localize the following components of the form view:
!
User interface components—Features of a view that users see, and
include:
!
Field labels
!
Selection field values
!
Banner names
These values are localized by manually entering the localized values
individually through the View Properties dialog box, or all together using
an automated procedure.
!
Message components—Underlying AR System messages and text, and
include:
!
System messages
!
Active Link Message
!
Filter Message
!
Help text linked to active link or filter workflow triggers
Localizing AR System Forms and Applications ! 113
!
Character menus
!
Form and field help
!
Descriptions and help text embedded within applications and guides
!
Labels for applications and guides
!
External files linked to applications or reporting
When the Localize Server field is checked (see Localize Server Setting on
page 135), the retrieval of messages is redirected from the default system
loaded dll to the AR System Message Catalog form. The AR System Message
Catalog form enables administrators to localize or customize messages, and
is populated using manual procedures or through automation.
An example of a customized environment would be as follows: An
administrator can take a single application and tailor the message
components to users needs, leaving the original application definition
untouched. AR System identifies and retrieves the localized or customized
messages from the AR System Message Catalog form. Messages for other AR
System system objects that were not customized are safely retrieved from the
systems default location because no entry for them exists in the AR System
Message Catalog form.
!
Automatically Generated Forms—These views are automatically saved
with the locale of en_US. If you need a web view of the form in another
locale, open the web view of the form on a machine set to the locale you
require, and save it.
Reporting
You can create localized reports by specifying a locale for a Report form
entry, and attaching a localized report definition file.
Locale-specific reports created using the run macro report action with
releases prior to AR System 5.0 can be converted to equivalent active links
(see Backwards Compatibility—Run Macro Report Actions on page 137).
Converting the run macro report action embeds the location of the localized
report within the active link.
Tasks for Localizing AR System Forms and Applications
Tools used to localize forms and applications are available throughout AR
System. The following checklist is provided to help guide administrators
through the complete process.
To achieve a complete, localized experience for users, you must create
localized views and applications using tools and settings within AR System,
and then apply the appropriate locale settings. This process consists of six
tasks, carried out in the following sequence:
1 Installing the available language dll(s)
2 Creating a localized view of a form
3 Localizing the user interface components of a view
4 Localizing messages, character menus, and reports
5 Localizing file menus
6 Applying the appropriate locale settings
The checklist provided in the following table describes each task and refers
you to the appropriate place in the documentation to successfully complete
the localization process.
Table 5-5: Localizing AR System Forms and Applications—A Checklist (Sheet 1 of 2)
Done
Task
Reference
Install the available language
dll.
See Selecting Languages During
Installation of AR System on page 117.
Create a localized view of a
form.
See Creating a Localized View of a Form
on page 119.
Localize the user interface
components of a view.
View components targeted for
translation include: field
labels, request aliases, and
selection field values.
This process is accomplished by
following an automated procedure or by
manually editing each field individually
on a view.
For the automated procedure, see
Localizing View Components Through
Export/Import on page 121.
For manual procedures, see Manually
Localizing View Components on
page 122.
Localizing AR System Forms and Applications ! 115
Table 5-5: Localizing AR System Forms and Applications—A Checklist (Sheet 2 of 2)
Done
Task
Reference
Localize messages, including
system error messages.
This process is accomplished by creating
entries in the AR System Message
Catalog form. You can populate the
AR System Message Catalog
automatically using the ARTEXT utility
and the
AR System Import tool. Or, an
administrator can manually place entries
in the AR System Message Catalog form
by opening the AR System Message
Catalog form in AR System Windows
User Tool.
For the automated procedure using the
ARTEXT utility and the AR System
Import Tool, see Automatically
Localizing Messages on page 125.
For manual procedures, see Manually
Localizing Messages on page 126.
Localize menus.
See Localizing Menus on page 131.
Set the Localize Server option This setting indicates to the server that
in AR System Administrator. workflow messages are being retrieved
from the AR System Message Catalog
form, rather than using default AR
System messages.
See Localize Server Setting on page 135.
Verify localized views in
AR System Windows User
Tool, and adjust the view size,
as appropriate.
Adjusting the size of a view allows for
label size variation between languages,
making it possible to fit field labels
within the borders of a view.
To adjust the size of a view in
AR System Administrator, see Adjusting
View Size in AR System Administrator on
page 136.
Set User Preferences for:
! Display locale
! Date/time formats
! Time zone
See AR System Windows User Tool
Preferences Settings on page 138.
Advanced Tasks
Advanced localization tasks include:
!
Set up email templates to accommodate the locale of the view created. See
Exporting Email Templates in Different Locales on page 137.
!
Export localized form views to another server. See Exporting a Single View
on page 137.
!
Localize report files created using macros. See Backwards
Compatibility—Run Macro Report Actions on page 137.
!
Access a localized view of a form in a browser. See Accessing a Localized
View of a Form in a Browser on page 140.
Selecting Languages During Installation of AR System
AR System supports English, French, German, Italian, Japanese, and Spanish
languages. Users can select a single language, or select multiple languages
during installation of AR System server and clients. To add languages not
selected during the initial install, the installation for each client must be run
again. English serves as the default language on all platforms, and users
cannot unselect it during installation.
During installation of the AR System Windows User Tool client and AR
System Alert, the language resource file, which holds AR System interface
translations, is stored within the resdlls directory found at the following
default location:
C:\Program Files\AR System\<client_sub-directory>\resdlls
In the resdll directory, each language installed is assigned a folder, identified
by a unique four-digit code:
!
German (0007)
!
English (0009)
!
Spanish (000a)
!
French (000c)
!
Italian (0010)
!
Japanese (0011)
Selecting Languages During Installation of AR System ! 117
During installation of the AR System server, the language resource file, which
holds system and error messages, is stored within the AR System server
directory found at the following default location:
C:\Program Files\AR System\<server_directory>
In the default server directory, each language installed has its own resource
file and follows the format: arcatalog_<language_code>.
The <language_code> follows the three-letter ISO 639 standard. The
following web site has a complete listing of the ISO 639 3-letter language
codes:
http://www.w3.org/WAI/ER/IG/ert/iso639.htm
Care must be taken when selecting the language options during installation
of each AR System client. Remedy does not support the use of AR System
client connected to an AR System server in a different character set. For
example, connecting a Japanese client to an English server and the reverse.
To view the system messages in the same language as your client, you need to
select your client language in the Components dialog box of the server
installation (only valid for Japanese, French, German, English, Italian, or
Spanish). If the client is set to a locale that is not provided, but that is
supported, you can add system messages to the AR System Messages Catalog
form for that locale, otherwise you receive system messages in the server’s
locale.
Installation of AR System server loads User selected translations of the
Group, User, User Preferences, Reporting, and Sample Application forms for
the languages supported by AR System. Administrators create additional
language-specific forms and applications using procedures in this chapter.
The ability to load multiple languages on to a single client machine enables
users to move seamlessly between languages by simply changing the
preferred locale setting. It also enables multiple users to share a single
machine by selecting a unique locale for each user.
Creating a Localized View of a Form
For each form you want to localize, you will need to create a localized view of
that form. You will use an existing view as the base for creating a localized
view. For information on creating form views, refer to the Developing AR
System Applications: Basic guide.
The Locale field on the Manage Views dialog box associates a language and
country dialect with a view in the following format: <language_country>.
Select only the language to include all variations of a language. For example,
if a user has fr_CA (French_Canadian) selected as a preference, but there is
no view created for fr_CA, then the view created with locale fr is displayed to
the user. So creating a view with locale fr will cover all french users, regardless
of whether the user’s preferred locale is fr_CA or fr_Fr
Figure 5-4: Manage Views Dialog Box—Locale Selection
The label name for the localized view, must be the same as the label name for
the view that is used as the base, when creating a localized view. This label
must then be selected in the Default View list. The label name selected in the
Default View list provides the selection base when AR System searches for the
preferred locale among views. When a user opens a form, the view selected
for display is determined by the following criteria.
Creating a Localized View of a Form ! 119
Searching for a View
AR System uses the following fallback lookup mechanism when selecting a
windows view for the user.
!
If a user indicates a locale as a preference in the Options dialog box in
AR System Windows User Tool, then the view that matches the selected
locale is used. It is first matched by language and country, and then by just
language if the country has not been specified.
!
If no locale preference is set, then a view with a blank locale, or the locale
of the user’s operating system is used.
!
If no locale preference is set and there is no view with a blank locale, then
an available view for the selected form is displayed to the user.
AR System uses the following fallback lookup mechanism when selecting a
web view for the user.
!
If the view with the locale specified in the URL is not found, then the view
with the user’s preferred locale will be loaded.
!
If the view with the user’s preferred locale is not found, then the view with
the locale of the web server is used.
For more information on how a view is selected for display, refer to the
After a locale-specific view is created, it is ready to localize.
Localizing the User Interface of a Form View
After a view is associated with a specific locale, the administrator can then
select that view and start the process of localizing view components that users
see. View components targeted for translation include:
!
Field labels
!
Request aliases—Banner names
!
Selection fields—Values linked to lists or radio buttons
Localizing View Components Through Export/Import
An administrator localizing a form view can export the view components
(field labels, request aliases, and selection fields) to a definition file using
exporting tools available in AR System Administrator. After the view
components have been exported to the file, they can be localized, and then
imported back into the form from where they were exported. The steps that
follow describe this process.
1 Open the file <server_directory>\CONF\ar.cfg if the server is on Windows, or
2
3
4
5
ar.conf on UNIX or Linux and add the line
XML-VUI-Export-Default-Is-Localized: T
In order to maximize the server’s performance, we recommend that you set
XML-VUI-Export-Default-Is-Localized: to False (F) if you do not intend to
localize the views you export.
Restart the server.
In AR System Administrator, select a server to administer.
Export view components to a file by choosing Tools > Export Definitions >
To View Definition File menu.
The export utility allows you to select multiple views for export, but the
output will be stored in a single file. You should export one single language
view at a time, giving each output a unique name.
When saving the export file, select XML for the format.
In the XML editor of your choice, translate the text located between the
<l10nCharacterValue> and </l10nCharacterValue> tags.
When modifying the XML file, be sure to keep the basic syntax and file layout
intact.
6 To import the translated view definitions back into the view from where they
were exported:
a Choose Tools > Import Definitions > From View Definition File in AR
System Administrator.
b Select XML as the file format.
c Check the Import in Place check box to replace the original view with the
localized version.
For more information on exporting and importing view definition files, see
Exporting and Importing Definitions on page 179.
Localizing the User Interface of a Form View ! 121
7 Verify the layout and field alignments and make adjustments, as appropriate
(see Adjusting View Size in AR System Administrator on page 136).
Manually Localizing View Components
The process of selecting every field on a view and entering the localized data
can quickly become a tiring task, especially if several form views are
associated with an application. This manual approach, however, is useful if a
specific view component (field labels, request aliases, and selection fields)
needs editing. These procedures will help you quickly locate field labels,
request aliases, and selection fields that simply need a quick fix.
Field Labels
Field labels are localized by entering the customized text in the Label field on
the Display tab in the Field Properties dialog box. Figure 5-5 on page 122
displays the Display tab in the Field Properties dialog box. For more
information on the Display tab properties, see the Developing AR System
Enter
localized text
here.
Figure 5-5: Field Properties Dialog Box—Display Tab
Request Aliases
The Request Aliases tab in the View Properties dialog box allows you to
define alias names to be used for native or web views. The fields on this tab
are localized by entering the appropriate text into the Singular, Plural, Short
Singular, and Short Plural fields. Figure 5-6 on page 123 displays the Request
Aliases tab in the View Properties dialog box. Only the Singular edit box is
available for web views.
For more information on the Request Aliases tab, refer to the Developing AR
Figure 5-6: View Properties Dialog Box—Request Aliases Tab
Selection Fields
Selection fields are lists and radio buttons. Administrators can modify the
values for these field types in the Attributes tab in the Field Properties dialog
box. The following procedure describes how to localize lists and radio
buttons. Figure 5-7 on page 124 displays the Attributes tab in the Field
Properties dialog box.
Localizing Display Values for Selection Fields Using AR System
Administrator
1 In AR System Administrator, open the form you want to localize.
2 Choose Form > View > Manage, and select a view.
3 Click on the Display button to open the selected view.
Localizing the User Interface of a Form View ! 123
4 Double-click a list or radio button field on the view.
5 Click the Attributes tab in the Field Properties dialog box.
6 Click the entry you want to modify in the Selection Value list, and enter the
localized text in the Alias Value edit box. Click the Modify button for each
entry that you modify.
7 Close the Field Properties dialog box.
8 Close the Manage Views dialog box.
9 Choose File > Save Form to save the form.
Enter localized
text here.
Figure 5-7: Field Properties Dialog Box—Attributes Tab
Localizing Message Components of a Form View
The AR System Message Catalog enables administrators to override system
default messages with equivalent localized or customized entries from the
AR System Message Catalog form. This override is indicated to the server
with an entry in the Server Information dialog box in AR System
Administrator (see Localize Server Setting on page 135).
When logged in to multiple servers, AR System first retrieves localized
messages from the preference server. If no preference server is available, it
uses the first localized server found when searching the user’s server list.
If a localized version for any message type is not found in the AR System
Message Catalog form, AR System loads the system default message.
Messages associated with any AR System object can be loaded into the
AR System Message Catalog form automatically with the AR System Import
tool, which uses as input a data file created from the ARTEXT utility (a tool
that is automatically installed in the same directory as the AR System server).
An administrator can also enter or modify messages manually by directly
opening the AR System Message Catalog form in AR System Windows User
Tool. The following section details each of these entry procedures for
populating the AR System Message Catalog form with localized messages.
Types of messages that can be localized include:
!
System Message
!
Active Link Message
!
Filter Message
!
Active Link Help Text
!
Form Help Text
!
Field Help Text
!
Container Description (includes applications and guides)
!
Container Label (includes applications and guides)
!
Container Help (includes applications and guides)
!
List Menu Definition (character menu)
!
External Report
!
Application Help
!
Application About
!
Application Help Index
Automatically Localizing Messages
AR System features a utility, ARTEXT, that extracts messages from
forms/applications workflow and inserts them into .arx, .csv or .xml file
formats. Once in a data file, the messages can be translated, and then
imported into the AR System Message Catalog form using the AR System
Import Tool.
Localizing Message Components of a Form View ! 125
ARTEXT is automatically installed with your server and resides in the server’s
installation directory. For information about using ARTEXT, refer to the
artext.txt file that is included with the utility.
For information on using the AR System Import Tool, see Chapter 8,
Importing Data into AR System Forms
Manually Localizing Messages
You can enter messages manually, which can help you verify the automated
process. Using the manual procedures that follow, you can also edit errors
within the AR System Message Catalog form without having to run the
automated procedure again.
Figure 5-8: AR System Message Catalog Form
Fields on the AR System Message Catalog form are relevant to some message
types, but not all.
Manually Entering Messages into the AR System Message Catalog
1 Open the AR System Message Catalog form.
2 Enter or select the appropriate data for the following key fields:
!
Message Type—The type of message you are localizing. Select the message
type from the list. Only the number value associated with the selected
message is entered in the Message Type field.
!
Message Identifier—The object whose messages you are localizing. Type
in the name of the object.
!
Locale—The locale for the message. If an administrator is storing localized
messages for multiple languages, and the AR System Message Catalog
form is enabled (see Localize Server Setting on page 135), then AR System
will compare the user’s preference setting for locale and attempt to match
an appropriate message from the catalog, when requested.
Type in the locale following the format: <language_country>.
For a list of standard choices for this field, open the Manage Views dialog
box in AR System Administrator (see Figure 5-4 on page 119). It is
recommended that only the language portion be entered, allowing for all
country variations of a language. For example, an entry of fr would include
all country variations of French.
!
Status—The status of localized messages to be retrieved. An Active status
enables a message for retrieval. Select Inactive if you do not want a
particular message accessed when a server is set as localized.
!
Field ID or Msg Num—The field identifier (Field ID) is found in the
Database tab in the Field Properties dialog box. The message number
(Msg Num) for an active link or filter message, is found in the If Action
tab in the Active Link dialog box.
!
Return Type—Setting that identifies whether text or file is returned when
the message is called.
The following table references each message type individually, noting the
entry requirements that uniquely identify it within a system object.
Table 5-6: AR System Message Catalog—Message Types (Sheet 1 of 4)
Message Type
Entry Description
System Message
1 Select System Message from the Message Type list.
2 Enter the error number in the Message Identifier
field.
3 Enter the locale in the Locale field.
4 Select Message Text for Return Type and enter the
localized text in the Message Text field.
Active Link Message
1 Select Active Link Message from the Message Type
2
3
4
5
Active Link Help Text
list.
Enter the name of the active link in the Message
Identifier field.
Enter the locale in the Locale field.
Enter the message number of the active link.
Select Message Text for Return Type and enter the
1 Select Active Link Help from the Message Type list.
2 Enter the name of the active link in the Message
Identifier field.
List Menu Definition
(character menu)
1 Select List Menu Definition from the Message Type
list.
2 Enter the character menu name in the Message
Identifier field.
Filter Message
1 Select Filter Message from the Message Type list.
2 Enter the name of the filter in Message Identifier
field.
4 Enter the message number in the Field ID or Msg
Num field.
Message Type
Entry Description
Form Help Text
1 Select Form Help Text from the Message Type list.
2 Enter the name of the form you are localizing in the
Message Identifier field.
Field Help Text
1 Select Field Help Text from the Message Type list.
2 Enter the name of the form you are localizing in the
Message Identifier field.
4 Enter the field identifier in the Field ID or Msg
Num field.
Container Description
1 Select Container Description from the Message
Type list.
2 Enter the name of the container in the Message
Identifier field.
Container Label
1 Select Container Label from the Message Type list.
2 Enter the name of the container in the Message
Identifier field.
Container Help Text
1 Select Container Help Text from the Message Type
list.
2 Enter the name of the Container in the Message
identifier field.
Message Type
Entry Description
External Report
1 Select External Report from the Message Type list.
2 Enter the name of the active link that the External
Report is linked to in the Message Identifier field.
4 Enter the File Id for the report in the Field Id or Msg
Num field.
Support Files are saved according to object name
and File ID. The File ID differentiates between
multiple support files when there is more than one
file or report associated with a single active link. The
administrator can identify how many reports or
files are associated with an active link, and then put
in the appropriate number; for example 1, 2, and so
on.
Another solution to finding the File ID is to export
the active link and review the .def file.
5 Select Binary Attachment for Return Type and
attach the localized report in the Binary Attachment
field.
Application Help
1 Select Application Help from the Message Type list.
2 Enter the name of the application in the Message
Identifier field.
attach a help file (.hlp) in the Binary Attachment
field.
Application help refers to the file attached in the
Help Text tab in the Application dialog box. This
message type is indicated by selecting the External
Help File radio button in the Help Text tab.
Message Type
Entry Description
Application About
1 Select Application About from the Message Type
list.
Identifier field.
attach an image file (.bmp, .jpeg, .jpg, .dib) in the
Binary Attachment field.
Application Help Index
1 Select Application Help Index from the Message
Type list.
Identifier field.
attach an index file (.cnt) in the Binary Attachment
field.
The help index (.cnt) file is the contents file used in
conjunction with the application help (.hlp) file.
Both will be used together only if the locale is
matched between them; otherwise, only the help file
is used.
Localizing Menus
A menu is a server object that contains items that the user selects. The items
in a menu can be defined within a character menu, or are retrieved from a file
menu. Though there are different types of menus in AR System, only
character and file type menus can be localized.
Localizing Menus ! 131
Localizing Character Menus
Character menus can be localized all at one time using the ARTEXT utility (see
Localizing View Components Through Export/Import on page 121).
Administrators can also localize Character menus manually by modifying the
values in the Menu Definition tab in AR System Administrator. The
following figure indicates the Value field in the Menu Definition dialog box
where the administrator enters the localized text for a selected menu item.
Enter localized text
here.
Figure 5-9: Modify Menu Dialog Box—Character Menus
For more information on Character menus, refer to the Developing AR
File menus require a separate procedure described in the section that follows.
Localizing File Menus
1 To localize File menus, open the file indicated in the path on the Menu
Definition tab and localize the entries in a text editor.
2 After you have finished editing, save a localized version of the text file in the
format: [filename].[file extension].[language_country].
AR System searches for the appropriate version of a file menu according to
what locale is set as the user preference.
Localizing Search Menus
Creating localized menus enables automatic searches on forms based on the
user’s locale.
To Create a Localized Search Menu
1 Open the AR System User Preference form
For each Windows user who is going to use the localized search menu:
a Click the Locale tab.
b Enter the Locale for that user in the User Locale field.
c Save the form.
For each web user who is going to use the localized search menu:
a Open the AR System Configuration Tool > General Settings tab.
b Ensure that the preference server names for the relevant users is set in the
Preference Server(s) tab.
2 Create your form that will contain the search menu.
3 Add a special field with field ID 160 to the form.
4 Create a Search menu on this form.
5 Invoke the Search menu.
The server automatically appends a query to the search statement, in which
the special field value equals the user’s locale.
Example:
Suppose the base query of a Search menu is:
“Create Date > 01/01/02”
Normally, when this query menu is executed, it will search for all records in
which the create date is greater than 01/01/02. If you add a field with field ID
160 to the form, the server will automatically change the search statement to:
“Create Date > 01/01/02 AND Field 160 = <user’s locale>”
Localizing Menus ! 133
Localizing Currency Types
You can localize the labels associated with currency types used in currency
fields. When you localize the currency labels, you associate them with a
particular locale. Users see labels corresponding to the locale specified in user
preferences when they select the menu that appears next to the field.
You will use the AR System Currency Label Catalog form to localize currency
labels. The AR System Currency Localized Labels form is used internally by
the system, and requires no modification.
Displaying Localized Currency Labels
AR System is available with the French, German, Italian, Spanish and
Japanese currency labels. The localized version displayed in the User tool will
depend on the user preference locale and the installed components selected
during the Server installation.
Localizing Currency Labels
For languages that are not supported:
1 In the User Tool, open the AR System Currency Label Catalog form.
2 In the Currency Code field, select a currency code from the list menu.
3 In the Locale field, enter the locale for which you are creating a localized
currency label.
For example, enter fr for all French languages. Enter fr_CA for French
Canadian.
4 Enter the localized string in the Localized Currency Label field.
5 Click Save to save the request.
Localizing the Mid Tier
In the mid tier, localized values such as menus, messages, text, and error
messages can be obtained only from the catalog server specified in the
Configuration Tool. (This is different from the AR System Windows User
Tool, which picks up localized values from the server where the form is
stored.)
To display localized components on the mid tier, ensure that:
!
A catalog server is specified in the Configuration Tool.
!
The Localize Server check box is selected for the catalog server in the
Server Information window of AR System Administrator.
!
An AR System Message Catalog form is present on that server and
contains the localized values you would like to access.
Settings and Procedures for the Localized Environment
Previous sections described procedures related to localizing form view
components. This section describes procedures used to finalize or fine-tune
a localized environment. Some tasks in this section are required, such as the
Localize Server Setting procedure, and appear in the Tasks for Localizing AR
System Forms and Applications on page 115. Other tasks may be appropriate
for some environments, and you can implement them as appropriate.
AR System Administrator Settings and Procedures
Settings and tools described in this section apply only to AR System
Administrator.
Localize Server Setting
You must select the Localize Server option in AR System Administrator to
enable the AR System Message Catalog form. If the AR System Message
Catalog form has been populated with locale-specific or customized
messages, you must select this option for those messages to be retrieved.
To indicate to the server that messages are retrieved from the AR System
Message Catalog form, rather than from the system default server, perform
the following steps.
Setting the Localize Server Option
1 In AR System Administrator, choose File > Server Information.
2 Click the Advanced tab.
3 Check the Localize Server check box.
4 Click the Apply button to enable the change.
5 Click the OK button to close the Server Information dialog box.
For more details on this setting, refer to the Configuring AR System guide.
Settings and Procedures for the Localized Environment ! 135
The following figure displays the Advanced tab in the Server Information
dialog box with the Localize Server check box indicated. The Catalog Form
Name field is read-only.
Check to enable
message retrieval
from the
AR System
Message Catalog
form.
Figure 5-10: Server Information Dialog Box—Advanced Tab
Adjusting View Size in AR System Administrator
Localizing view labels can sometimes alter the display of a view, positioning
some fields where a user cannot see them. Modifying the view size allows a
view to adapt to label changes, whatever their size or shape.
Perform the following steps to modify the size of a view.
Adjusting View Size
1 With a view open, modify the size of the window frame using the resizing
handles at the edge of the view. As you adjust the view size, the size in pixels
is displayed in the lower-left corner of the view. Resizing the view enables the
Save button.
2 Choose File > Save from the menu.
The view will be displayed in the size that it is saved in when opened in AR
System Administrator or AR System Windows User Tool.
Backwards Compatibility—Run Macro Report Actions
Reports created using run macro report actions with releases prior to AR
System 5.0, and that are language-specific are made available to users by:
!
Converting the run macro report action to an equivalent active link
!
Attaching the active link to a workflow trigger, such as a button field, and
placing it on a form
!
Creating an entry in the AR System Message Catalog form
Refer to Backwards Compatibility on page 172 for details on how to convert
run macro report actions to equivalent active links, and attaching them to a
workflow trigger.
For details on the AR System Message Catalog form entry required for
localized reports embedded in an active link, see External Report on page 130.
Exporting a Single View
The following procedure describes how to move a single view from one
server to another. This feature is useful if many views are defined for a single
form, each with a different locale. You can export a view to any server, and
then use AR System Administrator to import the view definition into the
server where they are currently logged in.
Exporting Single Views
1 In AR System Administrator, select a server to administer.
2 Choose Tools > Export Definitions > To View Definition File.
3 For complete instructions on the options available in the Export View
Definitions window, see Exporting Object Definitions on page 179.
Exporting Email Templates in Different Locales
A mail template is a form used for submitting requests to the server through
email. The Export Mail Templates dialog box displays all views that exist for
a selected form. The localized view can be selected to create a localized email
template. Mail templates for locale-specific views should only be created after
the view has been completely localized.
For information on how to set up mail templates, refer to the AR System
Email Engine Guide.
AR System Windows User Tool Preferences Settings
Settings described in this section finalize the task of localizing AR System for
a locale-specific environment. Users or administrators can set AR System
Windows User Tool preferences.
Users logging in to web clients, or who want to have the same settings and
customizations available when logging in to multiple machines, must use
centralized preferences, and log in with a preference server. For more
information on centralized user preferences, refer to the Configuring AR
System guide. For more information on preference servers, refer to the
Choose Tools > Options in AR System Windows User Tool to display the
Options dialog box used for setting user preferences. Select the Locale tab,
which is used to set:
!
Display locale
!
Date/time styles and formats
!
Currency
!
Time zone
A null selection for any of the fields on the Locale tab defaults to the setting
of the user’s operating system, browser, or web server, depending on whether
a locale preference is set. Figure 5-11 on page 139 displays the Locale tab in
the AR System Windows User Tool Options dialog box.
Selecting which character set to use for entering data in AR System is
dependant on the operating system. Administrators should review the
manual for their OS platform for instructions.
Figure 5-11: Options Dialog Box—Locale Tab
Setting the Display Locale
Selecting a locale allows users to make entries following the prescribed
format for their native country and dialect. AR System server uses this setting
to identify and return localized information.
The Display Locale selection follows ISO Standards in the following format:
<language_country>. At login, the server will search for form views that
match the locale selected in the Locale tab.
Setting the Date/Time Style and Time Zone
AR System stores all Date/Time field values as integers relative to 00:00:00
GMT, January 1, 1970. AR System displays the Date/Time value relative to
the timezone of the client viewing the field. See Chapter 5 of the Developing
AR System Applications: Basic guide for more information.
AR System calendars follow the Gregorian format and display the month and
day of the week according to the selected locale.
The Long and Short options for Date/Time Style are based on the following
settings:
!
In a Windows environment, the date and time display format is based on
the Regional Setting Properties Control Panel. If the AR System server is
running under a different account name or using the default user
configuration and you are unable to change the regional properties, you
can set the ARDATE, ARDATEONLY, or ARTIMEONLY variable.
!
In a UNIX environment, the date and time display format is based on the
ARDATE, ARDATEONLY, or ARTIMEONLY variable for UNIX. If you do not
use ARDATE, the display format is the default format for the language
setting, with the time zone determined by the TZ environment variable.
For more information on short and long date/time formats, refer to the
Accessing a Localized View of a Form in a Browser
The mid tier shared directory contains locale-specific versions of the
web-based login and logout pages following the format: login_<locale>.jsp.
These files are loaded during the installation of AR System Mid Tier.
Users can access a localized version of a form view by specifying the locale
and deployed name of the view in a URL. If you installed the mid tier in the
default location, and you deploy an application using default settings, the
basic URL to open a web view is:
http://<host>/arsys/apps/<locale>/<server>/<application_web_alias>/
<form_alias>_<view_alias>.jsp
Note: The locale portion of the URL follows the format:
<language_country>.
For more information about locale-specific login and logout pages and about
accessing a form view in a browser, refer to the Developing AR System
6
CHAPTER
Creating Reports for the Web and
Exporting Data
Reporting features in AR System enable users to create, edit, and
produce professional reporting documents. This chapter covers
reporting components of AR System, and how they work together to
enable reporting on the web. Preference and configuration settings
required for web reporting using AR System and Crystal report types
are also discussed.
This chapter also contains information about exporting AR System
data for use in AR System forms, spreadsheets, or other applications.
!
Reporting on AR System Data on page 142
!
Preference and Configuration Settings on page 144
!
Defining the Web Reporting Environment on page 147
!
Report Definition Files on page 151
!
ReportCreator Form on page 152
!
Report Form on page 161
!
Running a Report on the Web on page 163
!
Backwards Compatibility on page 172
!
Exporting AR System Data to a File on page 173
Creating Reports for the Web and Exporting Data ! 141
Reporting on AR System Data
AR System reporting tools enable users to create reports based on requests
that meet search criteria specified by a user. Once a list of requests is
generated, you can run a report using those requests as input.
Reports are run within AR System Windows User Tool or through a web
browser. The layout and content of a data in a report is determined by a
report definition file, which can be created using tools in native or web
clients, or by using the Crystal Report Designer application.
For information on how to use reporting features in AR System Windows
User Tool, see AR System Windows User Tool Online Help. The following
sections describe AR System reporting using a web browser, and the steps
that an administrator must complete to enable the web reporting feature.
Web Reporting Components
The following components work together in AR System to enable web
reporting.
!
AR System Preference and Configuration Tool settings
!
Reporting forms—Forms that are loaded automatically during AR System
installation and whose entries work to define web reporting. If these forms
do not appear in the Open dialog box of AR System Windows User Tool
after installation, they can be imported using the reportforms definition
file, found in the default AR System directory (C:\Program Files\AR
System\Arserver\Samples).
The four reporting forms are:
!
!
ReportType
!
ReportCreator
!
Report
!
ReportSelection
Report definition files—Files that define the layout and content of data in
a report. These files are created and edited using the following tools:
!
AR System Windows User Tool reporting tools
!
The ReportCreator form on the web, and in AR System Windows User
Tool
!
The Crystal Report Designer application
142 "Chapter 6—Creating Reports for the Web and Exporting Data
!
A deployed web view of a form containing a table or results list
field—Table and results list fields hold the data that serves as input to a
report.
!
The Open Window active link—A workflow object that opens a browser
window for any form. For reporting, the Open Window active link is set
up to open the ReportSelection form in a browser window.
Web Reporting in AR System
The following steps outline the logical progression of tasks that an
administrator must complete to enable web reporting.
1 Configure AR System Windows User Tool preferences, AR System
Configuration Tool options, and Crystal web settings.
For information, see Preference and Configuration Settings on page 144.
2 Define the environment you are using to create, edit, and run reports on the
web with entries to the ReportType form.
For information, see Defining the Web Reporting Environment on page 147.
3 Make the ReportCreator and ReportSelection forms available to users on the
web.
Web views of the ReportCreator and ReportSelection forms are
automatically created during installation of AR System.
These views are automatically saved with the locale of en_US. If you need a
web view of the form in another locale, open the web view of the form on a
machine set to the locale you require, and save it.
4 Define a report definition file using AR System Windows User Tool
reporting tools, the ReportCreator form, or the Crystal Report Designer
application, and make the report available for selection on the web.
!
For information on creating or editing a report using AR System Windows
User Tool reporting tools, see AR System Windows User Tool Online
Help.
!
For information on creating or editing a report using the ReportCreator
form, see ReportCreator Form on page 152.
!
For information on Report form entries, see Report Form Entries on
page 161.
5 Define a table or results list field on a form to hold the data that serves as
input for a report.
Reporting on AR System Data ! 143
For information, see Reporting Using Table and Results List Fields on
page 166.
6 Generate an AR System or Crystal report through a web browser.
For information, see Running a Report on the Web on page 163.
Preference and Configuration Settings
Settings covered in this section refer only to web-related reporting options.
For information on settings required for native reporting, see AR System
Windows User Tool Online Help.
AR System Windows User Tool preference settings and configuration tool
options described in the sections that follow are required for web reporting.
Crystal Web settings are required only if a user wants to view reports created
with the Crystal Report Designer application on the web.
AR System Windows User Tool Preferences
To set user preferences in AR System Windows User Tool for web reporting,
follow these steps.
Setting AR System Windows User Tool Preferences
1 In AR System Windows User Tool, choose File > Open, and double-click the
AR System Windows User Tool Preferences form in the Open dialog box.
2 In the Advanced tab, set the Report server reporting options.
Enter the name of the server where the four reporting forms (ReportType,
ReportCreator, Report, and ReportSelection) reside. The server name
entered here will also serve as the home for report definition files.
This entry is necessary when the server where the reporting forms are stored
is different from the server where the data to be reported on resides. To gain
access to the report server indicated as a user preference, the user must log in
with a preference server. For a complete discussion on preference servers and
how they work, refer to the Configuring AR System guide.
3 In the Web tab, choose one viewer for the Crystal Report Viewer field.
Be aware that not all browsers support all of the listed viewers. For example,
Netscape does not support Active X. HTML is the most likely to work with
all configurations of supported browsers.
4 Save the form.
AR System Configuration Tool Options
To set configuration tool options for web reporting, follow these steps.
Setting Configuration Tool Options
1 Open the AR System Configurations Tool page in a browser with the
following URL:
http://<host_name>/arsys/apps/shared/config/config.jsp
Note: The arsys within the URL assumes that you used the installer-supplied
Web Application context path of /arsys/. If you used a different
context path, change arsys to the name you specified.
2 On the General Settings page, set the following options in the Crystal Reports
Location field:
!
!
If the web server that is serving Crystal Web is IIS, specify the
<host_name> of the web server machine. If you need to specify a port
number other than the default, you must include it in the string as follows:
<host_name>:port
If the web server that is serving Crystal Web is iPlanet 4.x or Apache,
specify the CGI path to the Crystal Web component server as:
<host_name>/cgi-bin/wcscgi.exe
where <host_name> is the name of the web server machine. If you need to
specify a port number other than the default, you must include it in the
string as follows:
<host_name>:port/cgi-bin/wcscgi.exe
Enter the server port number if you use the $CRTPORT$ keyword in the
Start Command edit box on the ReportType form for the Crystal report
type. This keyword is not used in the recommended Start Command.
!
Reporting Working Directory
Specify a directory where the web server will look for report definition
files. If this is not under the web server's root document directory, you
must configure your web server with a virtual directory to point to this
directory.
Preference and Configuration Settings ! 145
Crystal Web Settings
On a Windows platform, if you are using IIS as the web server (or NES 3.6.3),
the installation of Crystal Reports 8.5 should have already established the
setting necessary to view Crystal reports using Crystal Web. The Crystal
Reports Web Components server runs only on the Windows platform.
If you are using iPlanet 4.x or Apache as the web server, you must set up the
CGI connector to Crystal Web following this procedure.
Setting Crystal Web Settings
1 Create the directory, cgi-bin under the web server's document root:
C:\iPlanet\Servers\docs\cgi-bin
2 Configure the web server to enable CGI for this cgi-bin directory. Refer to
your web server documentation for details on how to do this.
3 Copy the file, wcscgi.exe from the Crystal Reports installation directory:
C:\Program Files\Seagate Software\WCS\wcscgi.exe), to the cgi-bin
directory
4 Test the configuration by trying to view the sample web reports that are
installed with Crystal Reports. These samples are accessed from the Windows
Start menu option for Seagate Crystal Reports.
It is important to test the sample web reports to eliminate this configuration
as a possible problem if Crystal reports later cannot be viewed on the web.
System Data Source Name (DSN)
Every AR System server that a report references will need a System DSN
(Data Source Name). The recommended format of this name is
<server_name>_DSN.
If the Crystal Report Designer application is on a different system than the
Crystal Web Component server, then an administrator must ensure that the
System DSN have the same names. For example, if an application developer
who is developing on Machine A has created a system DSN called
“myServer_DSN,” and the Crystal Web Component server is on Machine B,
then Machine B will also need to have a system DSN named
“myServer_DSN.”
AR System Report Plug-in
A report plug-in is used by the ReportCreator form to create an entry in the
Report form when submitting a new definition file. For more information on
plug-ins, see the Configuring AR System guide.
Defining the Web Reporting Environment
The ReportType form defines the environment that supports creating,
editing, and running reports on the web.
ReportType Form
Report types can be AR System, Crystal, or user-defined. User-defined
environments are defined using keywords listed in Start, Edit, and Create
URL Keywords and Descriptions on page 148. Only administrators may
submit or modify entries to this form.
To define a report type, follow this procedure.
Entering ReportType Form Data
1 In AR System Windows User Tool, open the Report Type form in New
mode.
Figure 6-1: ReportType Form
Defining the Web Reporting Environment ! 147
2 In the Report Type field, enter AR System, Crystal, or a user-defined name
for the supporting report engine.
3 In the Query Converter Class field, enter the name of the Java class that
converts an AR System query string into a query string format recognized in
the web reporting interface.
4 In the Query Override Capability field, enter Yes or No.
Selecting Yes gives this report type permission to override a query stored in a
report. A No selection denies this permission. This field also displays on the
ReportSelection form.
5 For the Start Command, Edit Command, and Create Command fields, enter
the URLs that are used to connect a report to the engine.
The keyword components of the string correspond to parameters that are
passed to the web reporting environment. The function of the Start
Command is to initiate processing of the selected report. Edit and Create
commands initiate the ability to modify and create reports on the web.
The following table lists allowable URL keywords that can be used to build
the Start, Edit and Create commands. These keywords listed are for reporting
purposes only. They are not AR System keywords.
The recommended Start, Edit, and Create commands are single line entries
with no spaces. Since you can only view Crystal reports on the web, only the
Start Command is required for the Crystal report type.
Table 6-1: Start, Edit, and Create URL Keywords and Descriptions (Sheet 1 of 2)
Keyword
Description
$USR$
User name.
$PWD$
User’s password.
$RPTOP$
Operations (Start, Edit, Create).
$RPTFORM$
Form the report is being run against.
$RPTSVR$
Name of the server where the form is located.
$RPTNAME$
Name of the report.
$RPTLOC$
Report location relative to the base directory for
reports as indicated in the Configuration Tool.
$RPTFILE$
The report on the web server. An absolute pointer
to where the report file is found.
Table 6-1: Start, Edit, and Create URL Keywords and Descriptions (Sheet 2 of 2)
Keyword
Description
$RPTQUERY$
Query string.
$RPTQOVR$
Query override.
$CRTSVR$
Crystal web server. This is usually the same as the
AR System server mid-tier web host.
$CRTPORT$
Crystal web server port.
$CRTVWR$
Crystal report viewer.
$LOC$
Locale used for generating locale-specific prompts,
labels, and formatting data.
$TIMEZONE$
Time zone to use for generating date and time
strings; for example, PST.
$LANGUAGE$
Language to use for formatting data.
$COUNTRY$
Country where the language is spoken.
$UPRPTSVR$
AR System server that is specified in the user
preferences as the Report Server.
The following entries are recommended for the Start Command, Edit
Command, and Create Command fields for the AR System and Crystal
report types. The recommended entries for AR System and Crystal report
types are loaded automatically during AR System installation.
!
Native AR System Reports
!
Report Type—AR System
!
Query Converter Class—<leave blank>
!
Query Override Capability—No
!
Start Command—/arsys/servlet/com.remedy.arsys.
reporting.NativeReportServlet?O=$RPTOP$&U=$USR$
&P=$PWD$&Q=$RPTQUERY$&S=$RPTSVR$&F=$RPTFORM$&R=$RPT
NAME$&RF=$RPTFILE$&LOC=$LOC$&TZ=$TIMEZONE$&LNG=$LANG
UAGE$&CTRY=$COUNTRY$
Defining the Web Reporting Environment ! 149
The arsys at the beginning of the Start Command assumes that you
used the installer-supplied Web Application context path of /arsys/ in
ServletExec 3.1. If you used a different context path, change arsys to the
name you specified. However, you should use the context path supplied
by the installer, which configures ServletExec so that no conflicts arise
when using different web servers with one report server.
!
Edit
Command—/arsys/servlet/ViewFormServlet?formfield=17127&serv
er=$UPRPTSVR$&mode=query&qual=%278%27%3D%22$RPTNAME$%
22&enc=$RPTENC$
Create Command—/arsys/servlet/ViewFormServlet
?formfield=17127&server=$UPRPTSVR$&mode=submit&qual=%3Co
m%3E%3Cfid%3E17121%3C%2Ffid%3E%3Cvt%3E4%3C%2Fvt%3E%3Cval
%3E$RPTSVR$%3C%2Fval%3E%3Cfid%3E17127%3C%2Ffid%3E%3Cvt%3
E4%3C%2Fvt%3E%3Cval%3E$RPTFORM$%3C%2Fval%3E%3C%2Fom%3E
Crystal Reports
! Report Type—Crystal
!
!
!
Query Converter Class—com.remedy.arsys.CrystalQueryConverter
!
Query Override Capability—No
!
Start
Command—http://$CRTSVR$/arreports/$RPTLOC$?init=$CRTVWR$
&User0=$USR$&Password0= $PWD$&SF=$RPTQUERY$
The $RPTLOC$ parameter refers to a report file location relative to the
directory specified as the Reporting Working Directory in the AR
System Configuration Tool. Refer to AR System Configuration Tool
Options on page 145 for information on configuration tool options. If
the directory specified in the AR System Configuration Tool is not the
web server's document root, you must include the web server's path to
the configured directory before the $RPTLOC$. In this example,
“arreports” is a virtual directory configured on the web server to point
to the parent of $RPTLOC$.
!
Edit Command—<leave blank>
!
Create Command—<leave blank>
Report Definition Files
Report definition files define the layout and content of data on a report. You
create them using the following design tools:
!
AR System Windows User Tool reporting tools
!
ReportCreator form on the web, or in AR System Windows User Tool
!
Crystal Report Designer application
To make a report available for a user to select in the ReportSelection form,
attach a report definition file with an entry to the Report form.
AR System Reports
Users can create AR System reports in AR System Windows User Tool by
using reporting tools or by using the ReportCreator form. You can create
reports on the web only by using the ReportCreator form.
New and existing AR System reports are made available for web reporting
with an entry to the Report form. Reports created using the ReportCeator
form automatically create an entry to the Report form when submitted.
Existing AR System reports created using run macros can be converted to
external reports. For more information, see External Report on page 130.
For information on creating and editing AR System reports using AR System
Windows User Tool reporting tools, see AR System Windows User Tool
Online Help.
For information on creating and editing AR System reports using the
ReportCreator form on the web, see ReportCreator Form on page 152.
Crystal Report Designer
Crystal reports are created using the Crystal Report Designer application,
which is a Windows application that Seagate Software sells separately. Report
definition files created using the Crystal Report Designer application are
saved with the file extension .rpt. Once saved, they must then be made
available for web reporting with an entry to the Report form. Additional
Crystal web-related settings that may need to be configured depending on
the web server installed. Refer to Crystal Web Settings on page 146 for more
information.
Report Definition Files ! 151
Updating Crystal Reports
If the form fields are modified, especially fields on which a Crystal report is
reporting, then you must update the Crystal report; otherwise, you will
receive the following error message: “Error detected by database DLL. [On
Report Server: <server_name>].”
To update the Crystal report, open the report in Crystal Designer. Choose
Database > Verify Database. If the report is up-to-date, a message appears to
notify you. If it is not up-to-date, a message appears stating, “The database
file <file_name> has changed. Proceed to fix up the report?” Click Yes. You
will need to map your report fields to the updated report. After doing so, save
the report and re-attach it to the corresponding entry in the Report form.
ReportCreator Form
A web view for the ReportCreator form is available after installation of AR
System.
The ReportCreator form is used to create or edit AR System report definition
files in AR System Windows User Tool or on the web. When you create a
report definition file using the ReportCreator form, a Report form entry is
automatically created when a user clicks the Submit Button on the
ReportCreator form, making the report available for selection on the web.
When users open the ReportCreator form for creating or editing reports
from the Report Selection window, the FormName field is filled
automatically only if no aliases are specified for the form that opens the
Report Selection window. The data dictionary menu attached to FormName
field is defined to show Plural request aliases of forms (or form names if there
are no aliases). As workflow has no access to Plural request alias, the
FormName field cannot be populated.
The FormName field is populated only when no aliases are defined on the
originating form. If the FormName field is not populated, you need to
manually choose a form name from the menu.
The following figure displays the ReportCreator form with sample entries for
creating a report definition file called UserGroup.
Figure 6-2: Report Creator Form
Creating a Report Definition File
Users can access the ReportCreator form by clicking the Create button on the
ReportSelection form. For information on accessing the ReportSelection
form, refer to Directly Accessing the ReportSelection Form Through a Browser
on page 164.
Users can also access the ReportCreator form directly with a URL. If the
default directory was selected during installation of the AR System mid tier,
use the following URL to access the ReportCreator form in a web browser:
http://<host_name>/arsys/apps/<locale>/<server_name>/<application_w
eb_alias>/ReportCreator_WebView.jsp
ReportCreator Form ! 153
Web Application context path of /arsys/ in ServletExec JSP Engine. If
you used a different context path, change arsys to the name you
specified.
Creating Report Definition Files Using the ReportCreator Form
1 When entering the ReportCreator form from the ReportSelection form,
select AR System from the Create Type list, and then click the Create button.
2 In the Report Name field, enter a unique, locale-specific name for the report.
3 From the Report Format list, select one of the following choices for the
format of the report.
!
Record—Displays each field of the request on a separate line.
!
Column—Displays each field as a column heading, and displays
information from each request in a separate row.
!
Compressed—Compresses the information with commas, white space, or
any other specified character between the columns. On the web, the
compressed format is viewed in a column format.
!
CSV—Displays with commas between the columns. Many spreadsheet
applications accept comma-separated files as input. The file extension.csv
is attached to the file name.
!
AR Export—Stores data in a format compatible with AR System Import.
The file extension .arx is attached to the file name.
!
XML—Stores data in XML format. This format is useful when there is a
need to share data between applications. The file extension .xml is attached
to the file name.
The CSV, AR Export, and XML formats are not available for web
reporting.
4 In the Server name field, enter the name of the server where the form being
reported on is located.
5 In the Locale field, enter the locale of the report following the format:
<language_country>
For a list of standard choices for this field, open the Manage Views dialog box
in AR System Administrator. Only the language portion should be entered,
allowing for all country variations of a language. For example, an entry of fr
would include all country variations of French.
6 In the Form Name field, click the menu button to select the form from which
data is being reported on.
7 In the Report Set field, enter a local-independent description for the report.
The Report Set field is used to identify locale variants of the same report. The
combination of Report Set and Locale must be unique.
8 Update each of the ReportCreator form tabs as described in the following
section. Entries that are specific to Windows are identified in each of the tabs.
Fields Tab
In the Fields tab, define which fields on the form, from which data is being
reported on will be included in the report. Fields that apply only to the
Windows platform are indicated.
1 In the Field field, click the menu button to select which fields on the specified
form will display on the report.
2 In the Label field, enter the field name as you want it displayed on the report.
3 In the Width field, enter the field size, defined by character length, for
column- oriented reports. This option is for the Windows platform only.
4 In the Field to Add Before/After field, select a field to use as a reference when
clicking the Add After or Add Before buttons.
5 Click the Add Before or Add After buttons to set the positioning of fields in
a report, with reference to the Field to Add Before/After field.
6 Click the Modify button to update the selected field label or width
specification.
7 Click the Remove button to remove a selected field.
8 Click the Remove All button to remove all selections from the field list.
Sorting Tab
In the Sort tab, select fields to sort on and set the sort order and grouping for
each field for the report. You can select up to five fields for sorting.
1 From the first Field Name list, select the field you want to sort by.
2 Select Ascending or Descending Sort Order for the selected field.
3 To group by a field, choose the Group check box for the selected field.
4 Repeat steps 1 through 3 for the other fields you want to sort.
Statistics Tab
In the Statistics tab, define expressions that will calculate statistics for the
requests contained in the report. Use the Statistics tab to specify what type of
statistics to include. Fields that apply only to the Windows platform are
indicated.
1 From the Operation field, select the appropriate operation.
!
Count—Tallies the number of requests.
!
Sum—Adds up specified fields or the arithmetic relationship among
fields.
!
Average—Calculates the average of specified fields.
!
Minimum—Calculates the minimum value for a specified field.
!
Maximum—Calculates the maximum value for a specified field.
Except for Count, these operations can be applied only to numeric and
date/time fields. Each operation can apply to the whole report, or to a group
of requests in a report. Groups are defined in the Sorting tab.
2 From the Expression field, select a field from the menu list to include as part
of a statistic.
An expression is required for all statistical operations except Count. Whether
you include an expression for a Count operation depends on how you want
rows with null values to be counted.
If you are defining a Count operation that includes an expression, only rows
with a value that is not null for the specified expression are counted when the
report is run. If you are defining a Count operation that does not include an
expression, all rows returned are counted, including those with null values.
The menu list displays all numeric or date fields in the form. Expressions can
include any of the following values:
!
Numeric fields
!
Date fields
!
Status history fields
!
Keywords
The most commonly used keywords are: $DATE$, $NULL$, $TIME$,
$TIMESTAMP$, $USER$, and $WEEKDAY$. Keywords are case-sensitive
and must be entered in all capital letters. For a complete list of AR System
keywords, refer to the Developing AR System Applications: Basic guide.
!
Numbers
You can type numbers directly into the Expression field; for example, 5.25,
33, and so on.
!
Arithmetic operators (+, -, *, /, and %)
You can type arithmetic operators directly into the Expression field,
similar to the way they are entered in the advanced search bar.
3 In the Label field, type the label to identify a statistic on the report.
You can use text, keywords, or field values, and enter as many as 128
characters. To use keywords for the Label field, click the menu list and select
the appropriate keyword. Include one of the following results formats:
%* %
%#%
%:%
Default format
Numerical format (total number of seconds)
Time format (hh:mm:ss; hours, minutes, and seconds)
On the report, the statistic will display inside the label. For example, a label
created as: Statistical result is %#% days, will appear on the report as,
Statistical result is 123 days.
You can also include any of the following control characters in a label field:
\b
\n
\t
\\
\<nnn>
Backspace
Return
Tab
Backslash
ASCII character
4 From the Compute On field, select the scope of a statistic.
You can determine whether a statistic is calculated for the entire report, or
for defined groups within the report by selecting the appropriate setting in
the Compute On field.
!
Report—Calculates the statistic for all entries in the report. The statistic
appears at the end of the report.
!
<Group level>—Calculate a statistic for groups defined in the Sorting tab.
The statistic appears below each group.
5 In the Layout field, for the Windows platform only, specify how you want the
results to be displayed in the report by choosing one of the following options:
!
Single—Displays all the statistical results on one line.
!
Multiple—Displays each statistical result on its own line.
!
Column—Displays the result for each value at the bottom of the column
of the field specified in the Expression field. Column is valid only for a
column-formatted report.
The Layout field setting works with the Compute On setting to determine
where a statistic displays on a report.
Page Setup Tab
In the Page Setup tab, specify the page configuration information. Fields that
apply only to the Windows platform are indicated.
1 In the General section:
!
Enter the name of the report in the Title field. The report title appears at
the top of the report.
!
Enter text in the Header field. The header appears at the top of every page.
!
Enter text in the Footer field. The footer appears at the bottom of every
page.
To use keywords for the Title, Header, and List fields, click the menu list and
select the appropriate keyword.
2 In the General (windows) section:
!
In the Column Titles Per field, select where you want the column title to
appear in the report.
!
In the Long Field Format field, determine whether fields are wrapped to
the next line, or truncated when no more space is available on the page.
3 In the Margins (windows) section, specify the page margins for the report.
4 In the Separators (windows) section:
!
Enter characters in the Column field. These characters are used as
separators between columns in a column, or compressed text-formatted
report. The default value is a space. Besides any alphanumeric character,
you can also use control characters.
!
In the Request field, enter the character you want to use to separate
requests. The default character is an empty space.
!
In the Column Title field, enter the characters you want to use to separate
the column title (the field name) from the data below. This setting applies
only to column-formatted reports. The default character is a hyphen (-).
5 In the Size (windows) section:
!
Select Portrait or Landscape for the page orientation.
!
Set the Lines Per Page and Char Per Line values.
!
In the Page Break Per list, select an option to set when a new page is
started.
Qualification Tab
In the Qualification tab, specify which records to include in a report. If a
report is run from a results list, any qualifications defined in this tab are
ignored. For information on building qualifications, refer to the Developing
AR System Applications: Basic guide.
Description Tab
In the Description tab, enter a description of the report. This field is for
documentation purposes only.
Permissions Tab
In the Permissions tab, use the Assignee Groups field to define who has access
to a report.
If the server is configured to allow multiple groups in the Assignee Group
field, then this field will allow multiple groups to be specified, separating each
group with a single space. If the server is not configured to allow multiple
groups, then only one group can be specified in this field.
Leaving the Assignee Groups field blank allows only the submitter to view the
report.
Administration Tab
In the Administration tab, enter the user name of the person who is creating
the report, and define the status of the report. The fields on this tab are
required.
1 In the Submitter field, enter the name of the user creating the report.
2 Select Pending, Active, or Inactive for the Status field.
Select Active in the Status field to make this report available for selection in
the ReportSelection form. If Inactive or Pending is selected, the report will
not appear for selection in the ReportSelection form, unless the current user
is the submitter of the report.
Form Buttons
The following table describes the function of each button at the bottom of the
ReportCreator form.
Table 6-2: ReportCreator Form Buttons
Button
Description
Set to Defaults
Places default values in fields, where appropriate.
New Request
Clears all entries and places default values in fields, where
appropriate.
New Search
Clears the results list table and prepares the ReportCreator
form for a new search of available reports.
Modify
Opens the selected report in the results list for modification.
Query
Lists all reports associated with the current server, and that the
current user has permission to use in the results list.
Submit
Creates a new report definition, attaching the report definition
file with an entry to the Report form.
Saving Report Definition Files
To save a report definition file using the ReportCreator form, click the
Submit button at the bottom of the ReportCreator form. Clicking the Submit
button automatically creates an entry for the new report definition file in the
Report form, and makes it available for selection in the ReportSelection
form.
Editing Report Definition Files
To edit an AR System report using the ReportCreator form, perform one of
the following steps:
!
Select a report in the ReportSelection form, and click the Edit button.
!
Use the New Search and Query buttons on the ReportCreator form to
search for ReportCreator form entries. Results of the search are listed in
the results list at the bottom of the ReportCreator form. A user can then
select an entry from the results list, and click the Modify button to edit the
selected report definition file.
Report Form
The Report form associates an existing report definition file with a particular
form. Attaching a report definition file to a Report form entry makes a report
available for web reporting in the ReportSelection form. The Report form
also provides the mechanism by which permissions to run a report are
granted to specified groups.
Report Form Entries
Report definition files created using AR System Windows User Tool
reporting tools, or the Crystal Report Designer application, will need their
own entries in the Report form, making them available for web reporting. An
entry to a Report form is automatically created for report definition files that
are created using the ReportCreator form. Administrators and users may
submit entries to this form.
The following figure displays the Report form with a sample entry for a
report called UserGroup.
Figure 6-3: Report Form
To associate a report with a particular form, complete the following
procedure.
Report Form ! 161
Attaching a Report Definition File with an Entry to the Report Form
1 In the Report Name field, enter a unique, locale-specific name for the report.
2 In the Report Set Name field, enter a local-independent description for the
report.
The Report Set Name field is used to identify locale variants of the same
report. The combination of Report Set Name and Locale must be unique.
3 In the Locale field, enter the locale of the report following the format:
<language_country>
For a list of standard choices for this field, open the Manage Views dialog box
in AR System Administrator. You should enter only the language portion,
allowing for all country variations of a language. For example, an entry of fr
would include all country variations of French.
4 Enter the Report Type.
Entries in this field identify the environment that supports creating, editing,
and running reports on the web. Report types displayed in the list are
retrieved from entries made in the ReportType form. The entries loaded
automatically during installation of AR System for this field are:
!
AR System
!
Crystal
5 In the Form Name field, enter the name of the form from which data is being
reported on.
6 In the Server field, enter the name of the server where the form being
7 In the Assignee Groups field, select from the list the groups who will have
permission to view and modify this report.
If the server is configured to allow multiple groups in the Assignee Group
field, then this field will allow multiple groups to be specified, separating each
group with a single space. If the server is not configured to allow multiple
groups, only one group can be specified in this field.
8 ‘In the Status field, enter Pending, Active, or Inactive.
Select Active to make this report available for selection in the ReportSelection
form. If Inactive or Pending is selected, then the report will not appear for
selection in the ReportSelection form, unless the user is the submitter of the
report.
9 Attach either the AR System report (.arr) or the Crystal report (.rpt) to the
Report Definition File attachment field.
Note: Modified reports must be deleted and re-attached to the Report
Definition File attachment field for changes to be recognized.
10 In the Short Description field, enter a description of the report.
11 Click Save.
Deleting Report Definition Files
To delete report definition files in AR System Windows User Tool, complete
the following procedure.
Deleting Report Definition Files
1 Open the Report form in AR System Windows User Tool.
2 Click the Search button to list all Report form entries.
3 Select the entry you want to delete from the results list.
4 Choose Actions > Delete.
Deleting Report Definition Files on the Web:
1 Open the Report form on the web.
2 Run a query to list all Report form entries.
3 Select the entry you want to delete from the results list.
4 Click the Delete button.
Rather than completely deleting a report definition file, you can make it
unavailable by selecting Inactive in the Status field on the Report form for a
particular report entry.
Running a Report on the Web
The ReportSelection form, when displayed in a browser, enables a user to
select a report to run. A user may select a single report by selecting a report
in the table field, and then clicking the Run button. You can open the
ReportSelection form on the web in three ways:
!
Directly accessing the ReportSelection form through a browser
!
Clicking the Report button at the base of a table or results list field, and
opening the ReportSelection form
Running a Report on the Web ! 163
!
Creating an Open Window active link, and attaching it to a workflow
trigger, such as a button field
Directly Accessing the ReportSelection Form Through a Browser
Installing AR System creates a web view for the ReportSelection form. This
form must be made available to users on the web to enable web reporting.
Figure 6-4: Report Selection Form
If the default directory was selected during installation of the AR System
mid tier, then the following URL can be used to access the ReportSelection
form:
http://<host_name>/arsys/apps/<locale>/<server_name>/<application_web_
alias>/ReportSelection_WebView.jsp
Web Application context path of /arsys/ in ServletExec 3.1. If you
used a different context path, change arsys to the name you specified.
When accessing the ReportSelection form directly with a URL, an additional
field appears on the ReportSelection form that would otherwise not be there
if opened from a table or results list field. The Form Server field indicates on
which server the data form is located for the selected report. Selecting a
report in the ReportSelection form may populate this field because it is
populated from the Report form’s Server field entry, which is optional. A
user can manually enter the server name into the Form Server field if known,
though, it is not required. If left empty, the server where the ReportSelection
form resides will be used to locate the selected data form.
Figure 6-4 on page 164 displays the ReportSelection Form with two reports
listed, and the UserGroup report highlighted for selection.
The following table describes the buttons and options on the ReportSelection
form and their functions as they relate to web reporting.
Table 6-3: Buttons and Options on the ReportSelection Form (Sheet 1 of 2)
Buttons and Options
Function
Refresh
Updates the report selection table with the reports
available to the user.
The table displays only reports that the user who is
currently logged in has permission to use.
If the user arrives at the ReportSelection form from a
table or results list field, then only the reports associated
with the form from which the table or results list field is
displaying data will be available for selection. A user’s
access permission is also considered.
If the user arrives at the ReportSelection form directly
by way of a URL, then all reports available on the server,
and that the user has permission to access, are
displayed.
Run
Runs the selected report. The user enables this button
when selecting a report.
Create
Opens the ReportCreator form allowing the user to
create a new AR System report definition file.
Edit
Opens the ReportCreator form allowing the user to edit
the selected AR System report definition file. The user
enables this button when selecting a report.
Close
Closes the window generated for the ReportSelection
form.
Table 6-3: Buttons and Options on the ReportSelection Form (Sheet 2 of 2)
Buttons and Options
Function
Override Query in Report Selecting Yes gives permission to override the query
stored in a report with a query from a table or results
list. A No selection denies this permission.
Note: By default, the Query Override Capability field
is hidden on the ReportSelection form and appears
only when you select a report whose type has Query
Override Capability set to Yes. By default, the AR
System and Crystal report types set this field to No,
since these report types do not implement this
feature.
Create Type
Entries in this field select the report engine that
supports creating reports on the web.
Form Server
Indicates where the form is located for the selected
report. This field only appears when accessing the
ReportSelection form directly from a URL. For more
information, see Directly Accessing the ReportSelection
Form Through a Browser on page 164.
Reporting Using Table and Results List Fields
Table or results list fields provide the mechanism for capturing and
displaying data to users. Either field type can be selected for reporting
purposes. You can create a table or results list field on a form using AR
System Administrator and choose to have reporting features associated with
the table or results list field.
Options in the Table Labels tab in the Field Properties dialog box for table
and results list fields allow an administrator to define which hyperlinks and
buttons are positioned at the base of a table or results list for reporting. For
information on setting table and results lists properties, refer to the
The available hyperlinks or buttons that can be associated with a table or
results list for reporting purposes are:
!
Select All
!
Deselect All
!
Refresh
!
Report (click this button to open the ReportSelection form)
The following table describes the hyperlinks and buttons at the base of the
table field displayed in Figure 6-5 on page 168 and their functions as they
relate to web reporting.
Table 6-4: Buttons and Hyperlinks in a Table Field
Buttons and Hyperlinks
Function
Select All
Selects all entries in the table to be included in a
report.
Selective reporting is also possible using the
following keystrokes:
!
Shift key—To report on a range of entries,
click an entry and hold down the Shift key.
Click another entry above or below the
original selection, and then release the Shift
key.
This action includes all entries between those
selected in a report.
!
Ctrl key—To report on multiple entries,
click an entry and then hold down the Ctrl
key. Continue to click the entries you want
to include in a report, still holding down
the Ctrl key. When you have finished
selecting table entries, release the Crtl key.
This action includes selected entries in a report.
Deselect All
Clears all selections in the table. If no entries in the
table are selected, the report will show all entries
that match the table query. If a table query has not
been defined, then all entries are printed.
Refresh
Updates the table with the most recent AR System
data.
Report
Opens a new browser window for the
ReportSelection form.
You cannot have more than one results list field on a single form, but you can
have multiple table fields on a single form. The following figure displays a
deployed web view of a form containing a table field defined to hold data
from the User form.
The following steps describe the tasks required to generate a report using a
table or results list field.
Generating Reports Using Table and Results List Fields
1 In a browser, open a web view of a form that holds a table or results list field
defined to report on data from a specified form.
The table has been defined with reporting hyperlinks and buttons.
Figure 6-5: Generating a Report Using a Table Field
2 After the table or results list field is refreshed, select the entries that you want
to include in a report, then click the Report button at the base of the table or
results list field.
A new browser window appears with the ReportSelection form, which lists
reports available to the user.
3 Select a report from the ReportSelection form and click the Run button on
the ReportSelection form to generate a report, such as the one displayed in
the following figure.
Figure 6-6: UserGroup Report Generated from the ReportSelection Form
Generating a Report Through an Open Window Active Link
The Open Window active link method of running a report is useful when you
want to run a specific report, with the same query each time. Within the
definition of the active link, the administrator directs the report to a specific
form, and also defines what requests to include in the report. After the active
link is defined, it can be attached to a workflow trigger, such as a button field.
When the user clicks the workflow trigger where the active link is attached, a
new browser window opens to display the report.
The following procedure describes the tasks required in creating an Open
Window active link for reporting. For general information about creating
active links and related properties, refer to the Developing AR System
Creating an Open Window Active Link for Web Reporting
1 In the Create Active Link window, make the following entries in the Basic tab:
a In the Name field, enter a name for the active link you are creating.
b In the Form Name box, check the form being reported on.
2 Make the following entries in the If Action tab:
a From the New Action list, select Open Window.
b From the Window Type list, select Report.
c From the Target Location menu, select New.
This causes a new window to open for each report generated. Select
Current to use the existing open window from where the active link is
initiated. Type the name of a frame to open the report in the specified
HTML frame.
d From the Server Name list, select a server.
This is the name of the AR System server on which the form being
e From the Form Name list, select a form.
This is the name of the form being reported on.
f From the Form View list, select a view.
3 Create the following entries in the Qualification tab:
a Enter a query string determining which entries from the form to include
in the report.
If you want to get this string from a local field, you must use the EXTERNAL
keyword. For example, EXTERNAL($QueryStringField$). If this string and
the Entry IDs string are both empty, all entries in the form being reported
on are included in the report.
b In the If No Requests Match box, select Do Not Show Any Message.
4 In the Active Link dialog box, create the following entries in the Report
Information tab; within the If Action tab:
a In the Report Type field, select a report type from the menu.
b In the Name field, enter the name of the report as stored in the Report
form.
This is the report name in the Report form, not the file name of the
attachment.
c For the Target field, select Screen from the menu.
This entry must be Screen for web reports.
d For the Operation field, select Run, Edit, or Create from the menu.
This selection depends on what type of operation you want to perform. If
you want to create a new report definition file, select Create. To edit an
existing report definition file, select Edit. To run a report, select Run.
e In the Location field, select Reporting Form from the menu.
f In the Entry ID field, enter a comma separated list of entry IDs from the
form being reported on.
Only these entries are displayed in the report. If this string is filled and
contains fewer than 256 entry IDs, it overrides the Qualification String.
Otherwise, the Qualification String takes precedence. If both are empty, all
entries in the form are included in the report.
g For the Query Override field menu, select Yes or No from the menu.
Some report engines allow the Qualification String (or Entry IDs) to
override a query that might be stored as part of the report definition. This
value specifies whether the report engine should do so.
5 Click the Add Action button.
6 Save the active link and close the window.
Note: Check the Advanced check box at the bottom of the active link
window to select local field values from a menu for each attribute. For
more information about how to create an active link, refer to the
Attaching an Open Window Active Link to a Form with a Button Field
1 In AR System Administrator, select a web view of a form and create a new
button field where you want to attach the Open Window active link created
in the preceding procedure.
For more information on active links and attaching them to button fields,
refer to the Developing AR System Applications: Basic guide.
2 Choose File > Save to save your changes.
3 Redeploy the application that contains the form where you added the new
button field.
For information on deploying web-based forms and applications, refer to the
4 Open the form in a browser, and click the button field that contains the Open
Window active link.
Backwards Compatibility
Macros are not supported in AR System 5.0. You can view reports created
using run macro report actions with releases prior to AR System 5.0 in
AR System Windows User Tool, or on the web, by converting them to an
equivalent active link.
Running the conversion procedure for a run macro report action creates an
equivalent active link, which the administrator will be prompted to name.
The report content and layout (definition) become automatically embedded
within the active link during the conversion, and no additional entries are
required by an administrator. Once the active link is created, it can then be
attached to a workflow trigger, such as a button field, and placed on a form.
For details about the macro conversion procedure, refer to the Developing AR
For instructions on attaching active links to a workflow trigger, such as a
button field, see Attaching an Open Window Active Link to a Form with a
Button Field on page 171.
For information on backwards compatibility related to localization, see
Backwards Compatibility—Run Macro Report Actions on page 137.
Localized Reports
If you have language-specific reports created using run macro report actions
with releases prior to AR System 5.0, perform the following steps to make
them available to users:
1 Convert the run macro report action to an equivalent active link.
2 Attach the active link to a workflow trigger, such as a button field, and place
it on a form.
3 Create an entry in the AR System Message Catalog.
Refer to Backwards Compatibility for details on converting run macro report
actions to equivalent active links, and attaching them to a workflow trigger.
For details on the Ar System Message Catalog entry required for localized
reports embedded in an active link, see External Report on page 130.
Exporting AR System Data to a File
You can save or export AR System data to use in different AR System forms,
in a spreadsheet, or other applications. You can also save or export non-AR
System data from another application to use in an AR System form.
Obtaining Data from an AR System Source
You can import data from AR System Windows User Tool, a third-party
report writer, or an application that accesses AR System data.
To obtain the data from AR System Windows User Tool, generate a report,
and then export the data contained in the report to a data file. See AR System
Windows User Tool Online Help for instructions on how to do this.
If you plan to import the data into an AR System form using AR System
Import, you must export the data in one of the file formats listed in the
following table.
Table 6-5: AR System Export and Import Data Formats
Data Format
Extension
AR Export
.arx
AR XML
.xml
Comma-Separated Value (CSV)
.csv
ASCII
.asc
The format you choose will depend on the original data source and how you
will use the data. Data types are explained in the following sections.
AR Export
AR Export is the default file type, and yields the cleanest results when data is
exported and imported within AR System. The AR Export (*.arx) format is
designed to properly format data that is exported from AR System Windows
User Tool and that you will import into an AR System form using AR System
Import.
Exporting AR System Data to a File ! 173
Note: When an attachment is exported in AR Export format (*.arx), a
directory is created to store the attachment. The attachment directory
is created in the same directory as the *.arx file, and named with the file
name and an integer time stamp (for example,
<filename>_917732184). The *.arx file contains the directory name
and the names of the attachment files in it. If duplicate names exist,
prefixes are added to the attachment names to create unique file
names.
AR System XML
You can generate AR XML when exporting data from AR System Windows
User Tool. AR System XML is a Remedy XML standard derived from the
W3C XForm standard, and it contains several elements that are required for
AR System use. If you plan to import XML data into an AR System form
using AR System Import, your data must conform to the AR System XML
data specification. Data exported to the AR System XML file type in
AR System Windows User Tool conforms to this specification. You can also
convert XML data obtained outside AR System to the AR System XML
standard.
Conversely, you can export AR System XML data with AR System Windows
User Tool, parse it with any tool that parses documents that conform to the
XForm specification, and use the data outside AR System. For information
on XForms, refer to the W3C web site.
Note: Attachments are handled in the same manner as in the AR System
Export file type.
ASCII
To export data to ASCII format in AR System Windows User Tool, you must
use certain specifications. To ensure that the exported file is in a format
understandable to AR System Import. Use the following procedure to create
an ASCII file.
Creating an ASCII file
1 Create a report in compressed text format.
2 Open the report’s Properties dialog box.
3 Click the Page Setup tab.
4 Select Compressed Text in the Report Format section.
5 Leave the following fields empty:
!
Title
!
Header
!
Footer
6 From the Page Break Per field menu, select None.
7 From the Column Title Per field list, select Page.
8 In the Column field, enter a unique separator string that does not appear
anywhere in the data records, such as a semicolon (;).
Note that you will use this same separator string in the Field Separator field
of the Open Data File dialog box when you import the file using AR System
Import.
9 Click OK.
10 Choose Report > Export To > File.
The Report to File dialog box opens.
11 Specify the file name and destination directory.
a In the Save As Type field, select All Files (*.*).
b In the File name field, assign a name to the file, using the .asc extension.
c Select a destination directory from the Save In field.
12 Click Save.
Exporting AR System Data to a File ! 175
7
CHAPTER
Importing and Exporting Object
Definitions
This chapter describes the administrative tasks involved in managing
AR System objects. Managing objects of a particular server involves
exporting definitions from one server and importing them to another
server or into a source control system that has been integrated with the
AR System server. A definition is the description of the structure in
which the objects (forms, menus, filters, escalations, active links,
applications, packing lists, and guides) in AR System are organized,
identified, and manipulated in the AR System server.
!
AR System Object Definitions on page 178
!
Exporting and Importing Definitions on page 179
!
Exporting and Importing View Definitions on page 187
Note: Exporting and importing definition (.def or .xml) files is not the same
as importing data (.arx,.asc, .csv, or xml) file records. To export data,
you must use AR System Windows User Tool to export the data to a
file, as described in the online help for AR System Windows User Tool
and in Exporting AR System Data to a File on page 173. To import data,
you must use AR System Import, which is described in Chapter 8,
Importing and Exporting Object Definitions ! 177
AR System Object Definitions
You can move AR System objects from one server to another by exporting the
object definitions to a file, and then importing the definitions from that file
to a server on the same machine, or a server on another machine. Object
definitions are the descriptions of the structures featured in an application or
AR System solution. They contain no user data or entries. You can export
object definitions by type (for example, all menus), or you can export all
object definitions that pertain to a server.
To learn about exporting and importing data, refer to Chapter 8, Importing
Data into AR System Forms and Chapter 6, Creating Reports for the Web and
Exporting Data
When you export object definitions to a file, you choose a file type—AR
System definition or AR System XML.
The AR System Definition (*.def) File Type
The AR System definition file format is the default format for exporting
object definitions. It is a proprietary format for storing the definitions of AR
System structures.
The AR System XML (*.xml) File Type
Choosing the AR System XML format as the file format for exported objects
produces an XML document that is comparable to the AR System definition
file format. It is designed to follow the syntax of the XML specification 1.0.
Specifically, every AR System object type will have an associated structure
definition in XML, which is specified by the XML Schema Definition (*.xsd)
file. The *.xsd files reside on the AR System server and are used to validate the
AR System object definitions as valid XML.
Exported objects in XML format comprise an XML document, which may
also be referred to as an instance of a particular XML schema definition for
that object. If the XML schema definitions are loaded into an XML editor,
someone who is knowledgeable about AR System objects and XML can edit
the XML document.
178 "Chapter 7—Importing and Exporting Object Definitions
The XML schema definitions are designed to be similar to the definitions in
the *.def files. Refer to the data structure information in the AR System C API
Reference Guide, chapter 9 for more information on the XML Schema
definitions of AR System objects.
Exporting and Importing Definitions
Use the following AR System Administrator tools, accessed through the
Tools menu, to import and export definitions:
!
The Export Definitions tool—Exports structure definitions to a file. If you
are licensed for the Distributed Server Option, you can also export
distributed mapping and pool definitions. In addition, you can create mail
template files with the Export Mail Templates tool.
You can also export definitions into source control.
!
The Import Definitions tool—Imports structure definitions to a server. If
you are licensed for the Distributed Server Option, you can also import
distributed mapping and pool definitions.
You can also import definitions from source control.
Exporting Object Definitions
Exporting definitions to a file is the first step in moving object definitions
from one server to another. You can export one type or multiple types of
objects at a time.
Exporting Object Definitions to Definition Files
1 Select a server to administer.
2 Choose Tools > Export Definitions > To Definition File.
Exporting and Importing Definitions ! 179
The Export Definitions dialog box appears.
Figure 7-7: Export Definitions Dialog Box
The dialog box lists the available structure types. If you see a plus (+) next to
an object type, this means that at least one item of that type exists.
All object definitions from the specified server are displayed in the Objects on
<server> list. To see a more detailed list of available objects, click each object
icon.
3 Move the objects from the Objects on <server> list to the Objects to Export
list in any of the following ways:
!
Select available objects, and then click Add to add objects to the Objects to
Export list.
!
Select the object type, and then click Add to add all objects under the
selected type to the Objects to Export list.
!
Right-click on an object, and choose Add from the context menu.
!
Click Add All to add all the objects to the Objects to Export list.
!
Drag and drop objects between the Objects on <server> and Objects to
Export lists.
!
Double-click an object or an object type to move it to the other list.
4 As needed, use the Remove or Remove All buttons (or right-click option) to
move the selected objects from the Objects to Export list to the Objects on
<server> list.
5 Use the Add Related - All button (or right-click option) to move an object
and any objects that are related to it. (If using the drag-and-drop method,
press the Shift key while dragging to move related objects.)
If you do not click the Add Related - All button, only the selected objects
move to the Objects to Export list.
Each of the object definitions defined in the table below are exported as
follows when you use the Add Related - All button.
For:
Export Operation Includes:
Forms
All related menus, active links, filters, escalations, active
link guides, filter guides, web services, and distributed
mapping definitions. Forms associated with distributed
mapping definitions are exported with all related forms
and workflow on the current server.
Join forms
All related forms and their form-related items
Filters, active links, and
escalations
Guides
All related forms and their form-related items.
Applications
All related forms and their form-related items.
Packing lists
List of all objects in the packing list and the related items
of each object, including list of objects in an embedded
packing list. Exporting embedded objects can be time
consuming.
Menus
No related items will be exported.
Web Services
Flashboards
Exports as an independent object.
6 Use the Add Related - Restrict button (or right-click option) to limit the
scope of server objects when exporting shared workflow to a definition file.
This option defines new rules for each workflow object, establishing
parameters that restrict the objects that will be related to include only the
associations defined by the new rules (see the table that follows) for each type
of workflow.
Each of the object definitions defined in this table are exported as follows
when you use the Add Related - Restrict button.
For:
Export Operation Includes:
Forms
All related menus. active links, filters, escalations, active
mapping definitions. In addition, menus from the
Change Field action of the active links will be included.
Any other forms referenced in workflow actions, guides,
and menus will not be associated as related objects.
Join forms
All forms that were used to create these join forms as
well as their related items (as defined in the operations
included in the Forms above).
Active links
All menus that are referenced in the Change Field
actions, and all guides that are referenced in the Call
Guide action. The guides should refer to the same form
to which the active link refers. The active links that are
referenced in the guide also fall within the same scope;
therefore, the associated objects of those active links will
be included. This cycle continues until it reaches a form.
Filters
All filter guides referenced in a Call Guide action and all
DSO mapping definitions referenced in a DSO action.
Filters that are referenced in the guide also fall within the
same scope; therefore, the associated objects of those
filters will be included. The guides should refer to the
same form to which the filter refers. Escalations do not
have any of the above actions, so there will be no
associations for escalations.
Active link guides
All active links referenced in the guide as well as all
associated objects for those active links.
Filter guides
All filters referenced in the guide as well as all associated
objects for those filters.
Applications
All associated forms and the list of related objects
associated with those forms.
Packing lists
All contents of the packing list and all related objects for
those contents.
Menus
No related items exported.
Web Services
Flashboards
7 Select or clear the Export as Server-Independent check box to indicate
whether to remove references to the current server in your export definitions.
This option exists for backward compatibility for older servers. For 4.5 and
later servers, this option is obsolete as all definitions are stored independently
of server name.
If the check box is:
!
Selected (the default)—Removes all references, thus permitting
definitions in the export file to be imported to other servers.
If you are exporting menus and select this check box, include the following
option in the ar.conf (ar.cfg) file to ensure that the IP address does not
appear in the .def file:
IP-Name: <IP_address>
For more information about the ar.conf (ar.cfg) file, refer to the
!
Cleared—Embeds the name of the source server into the export file so that
definitions can only be imported to this server.
The Server Independent option keeps any references to other servers intact
during the export. References to the server from which you are exporting (the
source server) will change to reflect the name of the server to which you are
importing the object definition files.
8 Click Export to begin.
The Export File dialog box appears.
9 Specify where you want the definitions stored, and then save your changes.
All selected definitions are stored in a single file (with a.def or .xml
extension). If you specify an existing file name and location for the definition
file, a dialog box appears so that you can select the appropriate option:
!
Overwrite—Overwrites the object definition of an existing file. This
option is useful when you are re-exporting definitions that have changed.
!
Append—Appends the object definition to an existing file. This option is
useful when you are compiling definitions from several different servers in
a single location.
When the export is finished, an Export Complete message appears.
Click Cancel to close the Export Definitions dialog box.
Importing Object Definitions
The following section describes how to import object definitions to a server.
You also can import definitions into the AR System server from a source
control system. For example, you could update the current version of your
AR System server by using the import option to synchronize the AR System
server with the source control database. For more information, see
Integrating Source Control with AR System on page 216.
To import object definitions from definition files, you must already have
created an export file that contains the object definitions that you want to
import by using the procedure described in Exporting Object Definitions to
Definition Files on page 179.
Import operations involving many definitions can take a long time to
complete and require a large amount of database space. Your database must
have adequate resources before you begin the operation. Perform large
imports during hours when users do not require access to the system.
Importing Object Definitions from Definition Files
2 Choose Tools > Import Definitions > From Definition File.
3 Specify the name of the file (with a .def or .xml extension) that contains the
definitions that you want to import, and then click Open.
The Import Definitions dialog box appears.
Figure 7-8: Import Definitions Dialog Box
The dialog box lists the available structure types. If you see a plus (+) next to
an object type, this means that at least one item of that type exists.
All object definitions from the specified server are displayed in the Available
Objects list. To see a more detailed list of available objects, click each object
icon.
4 Move the objects from the Available Objects list to the Objects to Import list
in any of the following ways:
!
Import list.
!
selected type to the Objects to Import list.
!
!
Click Add All to add all the objects to the Objects to Import list.
!
Drag and drop objects between the Available Objects and Objects to
Import lists.
!
You cannot have two objects with the same name on a single server. If an
object in the import file has the same name as an object on the destination
server, you should take one of the following actions before completing the
import:
!
Remove the object with the same name from the destination server.
!
Rename the object with the same name on the destination server.
To rename an object, select it from the Objects to Import list, click again to
highlight the name, and type a new name.
Warning: If you rename a form in the Import Definitions dialog box and
then import the newly named form to the destination server, the
form will not retain the connection it had with its associated
workflow on the source server. To maintain the connection
between a renamed form and its associated workflow, you must
rename the form in AR System Administrator before you create
the object definition file. For more information about renaming
forms, refer to the Developing AR System Applications: Basic guide.
If you rename a menu, active link, filter, or escalation in the
Import Definitions dialog box, you must reattach it to the
appropriate fields on the destination server.
5 As needed, use the Remove button to move the selected objects from the
Object to Import list to the Available Objects list using any of the methods
described in the preceding step.
6 Click the Check in to Source Control check box to indicate whether to add
the object definitions to source control.
!
Cleared (the default)—Imports the object definitions to the destination
server.
!
Selected—Imports the object definitions to the destination server and also
checks the file in to Source Control.
!
Disabled—Source code integration is not enabled (in Enforced mode).
For more information, refer to Integrating Source Control with AR System on
page 216.
7 To overwrite an existing server object with the version from the .def or.xml
file, click the Import in Place check box.
Warning: If you overwrite an existing form, all previous data contained in
the form will be deleted or overwritten.
8 Click Import to import the definitions to the destination server.
The new definition names are added to the corresponding categories of the
server window. When the import is finished, an Import Complete message
appears.
10 Click Cancel to close the Import Definitions dialog box.
Exporting and Importing View Definitions
Exporting and importing view definitions use procedures similar to that of
object definitions. The differences are the initial menu option you select and
some extra fields in the dialog box.
To export view definitions, follow the same steps outlined in Exporting Object
Definitions to Definition Files on page 179, but choose:
Tools > Export Definitions > To View Definition File
instead of:
Tools > Export Definitions > To Definition File
Exporting and Importing View Definitions ! 187
The Export View Definitions dialog box appears.
Figure 7-9: Export View Definitions Dialog Box
The View Label, View Type, and View Locale fields list the details about the
selected view. If several Views have the same label, make sure that you import
the correct view locale.
To import view definitions, follow the same steps outlined in Importing
Object Definitions from Definition Files on page 184, but choose:
Tools > Import Definitions > From View Definition File
instead of:
Tools > Import Definitions > From Definition File
8
CHAPTER
AR System Import is a separate tool installed with AR System
Administrator and is designed to load data from a source file into an
AR System form. This chapter describes the AR System Import Tool
for Windows. A command line interface is also available, for both
Windows and UNIX. Refer to Chapter 16, Using Action Request System
from a Command Line for information on AR System client CLIs.
!
Understanding the Import Process on page 190
!
Preparing to Import on page 191
!
Defining AR System Import Preferences on page 194
!
Importing Data on page 206
!
Using a Saved Mapping File on page 211
!
Using the Import Log File on page 212
Note: This chapter explains how to import data. AR System Import does not
import object definitions to a server. For information about exporting
and importing definitions, see Chapter 7, Importing and Exporting
Object Definitions
Importing Data into AR System Forms ! 189
Understanding the Import Process
The import process loads data from a file into an AR System form. To import
data into a form, you must create a mapping that determines which pieces of
data to import into which fields on the target form (mapping), and configure
AR System Import to handle the import appropriately. This chapter
describes import concepts, and provides instructions for preparing to import
and performing an import operation.
Understanding Data Mapping
Mapping takes place during the import process. You can map all fields in a
data file to all fields in a form, or you can map fields individually. You must
map data the first time you import a specific data file into a specific form.
You can also define fallback mappings, which are default mappings that
direct the AR System Import response if a data mapping problem occurs
during an import. Fallback mappings are used when the data value is invalid
for the destination form field type. For example, if there is a problem while
mapping a value, the fallback mapping for the field is used, if one is defined.
If there is no fallback mapping, an error is generated. If there is a fallback
mapping and the fallback mapping fails, errors are generated on the original
failed mapping, not the fallback mapping.
The fallback mapping is not used when the error can only be detected by the
AR System server, such as when the data is not an acceptable value. For
example, the fallback mapping is not used if the data value is outside the
range set for the form field, or if a required field has a NULL value.
You can save mappings for future use. If you regularly perform a particular
import, saving the mapping saves time and reduces errors, because you load
the mapping file instead of entering the mapping values again. When you
save a mapping, all of the following import information is saved: the form
name, the server the form resides on, the data file name, fallback mappings,
and preferences.
Understanding Preferences
Preferences determine tool behavior such as how AR System Import displays
on screen, and import behavior such as how AR System Import resolves
conflicts during an import operation.
190 "Chapter 8—Importing Data into AR System Forms
Preferences may be stored in either of two locations. If you have access to a
preference server, preferences are stored in the AR System Administrator
Preference form on the preference server. If you do not use a preference
server, preferences are stored in the ar.ini file.
When you perform an import, the current preferences will determine how
AR System Import handles your data. You should verify that the current
preferences are appropriate for the import being performed before you map
the data or save the mapping file. This is important because the preferences
are set in the mapping file when you save it.
When you load a saved mapping file, the preferences specified in the
mapping file take effect. In other words, while a saved mapping file is loaded,
AR System Import reads preferences from the mapping file instead of the
ar.ini file or the preference server. The next time you log in to AR System
Import, the preferences from the ar.ini file or the preference server are
restored.
If you change preferences while you have a mapping file loaded, you must
save the mapping file again to save the new preferences for that mapping.
For more information on local and central preferences, refer to the
Preparing to Import
Before you import data into AR System with AR System Import, complete the
following tasks:
!
Define AR System Import preferences. Preferences are saved together with
data mappings (if you save your mappings), so set the preferences before
you save the mapping. Refer to Defining AR System Import Preferences on
page 194.
You might want to set different preferences for different import
operations. In that case, open the source data file and the target form first,
and then specify preferences for that particular import. Save the mapping
file according to step 10 on page page 210 to save the preferences for that
particular import.
Preparing to Import ! 191
!
Ensure that there is adequate space where the import log file will reside.
AR System Import writes error messages and failed records to a log, which
can become quite large. Refer to Using the Import Log File on page 212 for
more information. The default import log path is
<ar_home_dir>\import.log. To specify another path, refer to Defining
Desktop Preferences on page 195.
!
Ensure that there is adequate space in the database into which the records
will be imported. Contact your database administrator for assistance.
!
Export the source data to a file compatible with AR System Import.
Complete all edits on the data file before you start AR System Import. Do
not edit the data file between the time you open the AR System Import
application and the time you start the actual import operation. the
following table describes the supported data types.
Table 8-1: Supported File Types
File Format
Information
AR Export (.arx)
Default AR System data file type.
Created in AR System Windows User Tool or the
artext utility designed primarily for localization. To
create an AR Export file, refer to the AR System
Windows User Tool online help, or refer to
Automatically Localizing Messages on page 125 for
information on artext.
AR XML (.xml)
XML file conforming to the AR XML data
specification. Contains several elements that are
required for AR System use. Refer to the AR System C
API Reference Guide for more information.
Created in AR System Windows User Tool or the
artext utility designed primarily for localization. To
create an AR XML file, refer to the AR System
Windows User Tool online help, or refer to
Automatically Localizing Messages on page 125 for
information on artext.
XML files created outside AR System must conform
to the AR XML data specification.
Table 8-1: Supported File Types
File Format
Information
CSV (.csv)
Comma-separated value file.
Created in AR System Windows User Tool, another
application, or the artext utility designed primarily
for localization. To export a CSV file in AR System
Windows User Tool, refer to the AR System
Windows User Tool online help. To create a CSV file
with artext, refer to Automatically Localizing
Messages on page 125.
Carriage returns are treated as the end of the record.
ASCII (.asc)
Generic ASCII file, created in AR System Windows
User Tool with particular settings, or in another
application. To export an ASCII file from AR System
Windows User Tool, refer to AR System Windows
User Tool online help.
To use ASCII data obtained from a non-AR System
source, save the data with a unique separator string of
up to 32 characters in length. Use \t for tab, \b for
backspace, and \\ for \. Use this separator string
when you open a data file to import, as described in
step d on page page 207.
Carriage returns are treated as the end of the record.
Note: When an attachment is exported in AR Export format (*.arx) or
AR XML format (*.xml), a directory is created to store the attachment.
The attachment directory is created in the same directory as the *.arx
or .xml file. The file name is appended with an integer time stamp, like
this: myfile_ 917732184.arx. The .arx or .xml file contains the directory
name and the names of the attachment files in it. If duplicate names
exist, prefixes are added to the attachment names to create unique file
names. CSV and ASCII file types do not support attachments.
Preparing to Import ! 193
Defining AR System Import Preferences
Preferences define important tool behaviors, described in the following table.
For best results, verify that the settings are appropriate before you import
data. Preferences are saved with the data mappings when you save a mapping
file.
Preference
Function
Desktop
Defines the appearance and behavior of AR System
Import.
Duplicate Request ID
Defines how AR System Import processes records
that contain request IDs, which duplicate those
already in the form.
Error Handling
Defines how records that contain errors are
processed.
Data
Defines how data and values contained in the
source data file are processed.
Date/Time
Defines the date and time format of the data in the
source data file.
Confirmations
Defines the warnings, messages, and alerts
displayed during imports.
To use preferences from a saved mapping file, see Using a Saved Mapping File
on page 211.
All preferences are defined in the Preferences dialog box, as described in the
following procedure. Additional procedures describe how to set each
preference.
Accessing the AR System Import Preferences Dialog Box
1 Start AR System Import.
The main AR System Import window appears.
2 Choose File > Preferences.
The Preferences window appears (Figure 8-2 on page 195).
Figure 8-2: AR System Import Preferences Dialog Box—Desktop Tab
3 Follow the remaining procedures in this section to set preferences.
Defining Desktop Preferences
1 Select the Desktop tab in the Preferences dialog box, and set the following
preferences:
Maximize Application
Prompt for Login
! Cleared (default)—The application window opens
to the same size and position it was when it was last
closed.
! Selected—The application window is maximized
when you start the application.
Cleared (default)—Users are not prompted to log in
when AR System Import starts. Instead, the last user
who logged in to the tool is logged in.
! Selected—Users must log in to AR System Import
every time it starts.
!
Show Status Bar
! Selected (default)—A status bar is displayed at the
bottom of the application window, showing the
progress of the current operation.
! Cleared—The status bar is hidden.
Defining AR System Import Preferences ! 195
Show Tool Bar
Save Window Position
and Size on Close
! Selected (default)—A toolbar containing buttons
that correspond to various menu selections is
displayed.
! Cleared—The toolbar is hidden.
Selected (default)—The application window opens
to the same size and position it was when it was last
closed.
! Cleared—The application window opens to the
default size and position.
!
AR Path
This path identifies the directory where mappings are
saved, <ar_home_dir>\arcmds by default. You can
browse to a directory or enter the path manually.
Multiple paths must be separated with a semicolon (;).
Paths specified here are populated in the Save Mapping
dialog box. Refer to Figure 8-11 on page 210.
Import Log File
This path identifies the directory and file name of the
AR System Import log,
<ar_home_dir>\arimport.log by default. Error
details and records that fail during import are written
to this log. Failed records are those that cannot be
imported for some reason. The log file identifies these
records along with error messages. Refer to Using the
Import Log File on page 212 for information.
You can only specify one import log in this field.
However, each import can use a separate log. To
specify a different log for each import, save a mapping
for the import, which saves this path. When you begin
an import, specify the log for the new import and save
a mapping for the new import. When you load a
mapping, the import log path you specified will direct
AR System Import to write to the specified log.
Mappings are defined in the section Understanding
Data Mapping on page 190.
Reset Log File at Login
! Selected (default)—The import log is cleared each
time you start AR System Import.
! Cleared—New entries are appended to the existing
file. The file can grow quite large.
2 Continue with the remaining procedures to set additional preferences, or
click OK to close the Preferences dialog box.
Defining Duplicate Request ID Preferences
1 Select the Duplicate Request ID tab in the Preferences dialog box.
Figure 8-3: AR System Import Preferences Dialog Box—Duplicate Request ID Tab
2 Set the following preferences:
Generate New ID for All Default setting.
Records
New request IDs are assigned to all requests in the data
file, whether or not any IDs are duplicates. This
preference also generates request IDs for records that
do not already have them, for example, in a CSV file
created outside AR System.
Reject Duplicate Records Entries are imported using their existing IDs. If an ID is
already in use, an error is generated. The error is
processed according to your preferences. Refer to
Defining Error Handling Preferences on page 198.
Generate New ID for
Duplicate Records
Entries are imported using their existing IDs. If a record
with the same ID already exists in the database, a new
ID is generated for the imported record with the
duplicate ID.
Replace Old Record with Entries are imported using their existing IDs. If a
New Record
duplicate ID exists, the entire database record is
overwritten with the record being imported. You must
map the required core fields with this option. If
required core fields are not mapped, the server will
reject the records. For information on mapping, refer to
Importing Data on page 206. For information on core
fields, refer to Chapter 8, Importing Data into AR System
Forms
Update Old Record with Entries are imported using their existing IDs. If a
New Record’s Data
duplicate ID exists, only the fields being imported are
replaced, merging the record.
This setting also automatically makes all required fields
that are not core fields optional. Refer to Defining Data
Preferences on page 201 for more required field
preferences. For information on core fields, refer to
Chapter 8, Importing Data into AR System Forms
Defining Error Handling Preferences
1 Select the Error Handling tab in the Preferences dialog box.
Figure 8-4: AR System Import Preferences Dialog Box—Error Handling Tab
2 Set the following preferences:
Alert User with Popup
Dialog
Interrupts the import and displays an error message
(default). You have three choices.
! Yes—Skips the problem record, writes the error and
the record data to the import log and continues to
import remaining records.
! Yes to All—Skips all problem records that generate
the same error, writes the error and the records to
the import log, and continues to import remaining
records.
! Stop Import—Stops the import and prompts you
to copy all remaining data to the import log.
Refer to Using the Import Log File on page 212 for
more information.
Skip Bad Records
Skips problem records without displaying an error
message, and continues with the import.
Try Fallback Mapping
before Alerting User
If a mapping generates an error, AR System Import
uses the fallback mapping specified in the Fallback
Mappings preferences. If the fallback mapping also
generates an error, a message is displayed. The error is
generated against the original mapping error. Errors
are not generated against fallback mappings. Refer
also to Defining Error Handling Preferences on
page 198.
Import Records with Too Defines how AR System imports records that contain
Many Fields
more fields than described by the field titles in the data
file. The system checks each record individually. If the
check box is:
! Cleared (default)—The problem records are not
imported and an error is generated. The error is
! Selected—The problem records are imported and
the extra fields are ignored.
Import Records with Too Defines how AR System imports records that contain
Few Fields
fewer fields than described by the field titles in the data
file. The system checks each record individually. If the
check box is:
! Cleared (default)—The problem records are not
imported and an error is generated. The error is
! Selected—The problem records are imported with
NULL values in the missing fields.
Defining Data Preferences
1 Select the Data tab of the Preferences dialog box.
Figure 8-5: AR System Import Preferences Dialog Box—Data Tab
Note: These settings are affected by field attributes set when fields are
defined. Refer to the Developing AR System Applications: Basic guide.
2 Set the following preferences.
a You can choose one of the following options for character fields.
Remove leading and
trailing spaces and tabs
! Cleared (default)—Values are imported exactly as
they appear in the data file.
! Selected—All leading and trailing white space is
removed from each field imported.
Truncate strings exceeding If the check box is:
field limit
! Cleared (default)—Fields whose contents are too
long generate an error. The error is processed
according to your preferences. Refer to Defining
Error Handling Preferences on page 198.
! Selected—Fields that are too long are truncated.
Disable fields' pattern
matching during import
Defines if pattern matching is enforced by the server
during the import operation. If the check box is:
! Cleared (default)—Records are rejected by the
server if data in the field does not match the
specified pattern. An error is generated. The error is
! Selected—Records are imported, even if the data in
a field does not match the specified pattern.
b For required fields that are not core fields, you have only one option:
Make required fields
optional during import
Defines required fields that are not core fields as
optional during the import operation. If the check
box is:
! Cleared (default)—All required fields are treated as
required. If a required field has a NULL value, an
error is generated. The error is processed according
to your preferences. Refer to Defining Error
Handling Preferences on page 198.
! Selected—Required fields that are not core fields
are not enforced. NULL values are allowed in
required fields.
Defining Date and Time Preferences
1 Select the Date/Time tab of the Preferences dialog box.
Figure 8-6: AR System Import Preferences Dialog Box—Date/Time Tab
AR System Import accepts short or long date formats in the data file, and
ignores leading zeros.
2 Select the appropriate options.
Calendar Type
The default Gregorian calendar is the only choice.
Short Date Format
If you select:
M/d/yy—12/31/01 (default) is displayed.
d/M/yy—31/12/01 is displayed.
! yy/M/d—01/12/31 is displayed.
The sample text shows how the selected format
appears. The component order is based on the
Regional Settings in the Windows Control Panel.
!
!
Separator
(Date Format)
Defines the separator character between the month,
day, and year, with a slash (/) as the default. You can
use any character that is not part of the field
separator string for the data file. The sample text
shows the appearance.
Long Date Format
If you select:
!
dddd, MMMM d, yyyy (the default)— Tuesday,
December 31, 2002 is displayed.
!
dddd, d MMMM, yyyy—
Tuesday, 31 December, 2002 is displayed.
!
dddd, yyyy MMMM d—
Tuesday, 2002 December 31 is displayed.
!
dddd, MMMM dd, yyyy—
Tuesday, December 31, 2002 is displayed.
The sample text shows the appearance. The
component order is based on the Regional Settings
in the Windows Control Panel.
12 Hr
Tracks in the 12-hour clock (default setting).
24 Hr
Tracks in universal time.
AM/PM position
Enabled for 12 Hr only. If you select:
! Suffix (the default)—The symbol is positioned
after the time string (for example, 10:23:47 AM).
! Prefix—The symbol is positioned before the time
string (for example, AM 10:23:47).
AM symbol
Enabled for 12 Hr only. Defines the symbol that will
indicate morning.
PM symbol
Enabled for 12 Hr only. Defines the symbol that will
indicate afternoon.
Separator
(Time Format)
Defines the time format separator between the
hours, minutes, and seconds, with a colon (:) as the
default. You can use any character that is not part of
the field separator string for the data file. The sample
text shows the appearance.
3 Continue with the remaining procedure to set additional preferences, or click
OK to close the Preferences dialog box.
Defining Confirmation Message Preferences
1 Click the Confirmations tab of the Preferences dialog box.
Figure 8-7: AR System Import Preferences Dialog Box—Confirmations Tab
2 Select the appropriate options.
Confirm before deleting
all Mappings
If selected, a confirmation message appears when you
click Delete All in either the Import window or Fallback
Mappings dialog box.
Confirm before losing
Mappings
If selected, you will be prompted to save your work each
time you select a new form or file or exit AR System
Import without first saving.
Fallback Mappings
If selected, you will be prompted to save your work each
time you create a fallback mapping, and select a new
form or file, or exit AR System Import without first
saving.
New Mapping Value
If selected, a confirmation message appears whenever
you add or modify a mapping value without clicking
Add or Modify before exiting the window or starting
the import.
3 Click OK.
Importing Data
Importing data into a form involves loading a data file and a target form,
defining preferences for the import, and mapping data. To import data into
a form, you must have Change permissions for the fields to which you want
to import data. For system fields such as Create-date, you must be the
administrator or subadministrator of the schema.
The following procedure provides instructions for each step of the process.
Importing Data
1 Start AR System Import.
2 Log in if necessary, according to your defined preferences.
The AR System Import window appears.
Figure 8-8: AR System Import Window
3 Choose File > Open Form.
The Open Form dialog box appears.
4 From the Form Name list, select the destination form into which to import
data.
5 Click OK.
The destination form field names appear in the Form Fields list.
6 Choose File > Open Data File.
The Open Data File dialog box appears.
Figure 8-9: Open Data File Dialog Box
7 Identify the data file to import.
a From the Files of Type field list, select the file format.
Selecting All Files displays all data files, whether or not the formats are
valid import types. Selecting a data file with an invalid import format
generates an error.
b Navigate to the target data file and select it.
The file appears in the File Name field.
c If you chose CSV or ASCII as the file type, choose a title handling option:
If the first line of data contains titles, leave the File Contains Field Titles
check box selected so that AR System Import will not convert the titles
into data.
If the first line of data does not contain titles, clear this check box.
The check box is disabled for other file types.
d For ASCII format, enter the separator string you used when you created
the ASCII data file in the Field Separator field.
ASCII files must be generated with specific settings to be compatible with
AR System Import. Refer to the AR System Windows User Tool Online
Help for information on separator strings.
e Click Open.
The fields from the data file are loaded.
Importing Data ! 207
Note: If the data file contains duplicate field titles, an error is generated. If
the data is .arx or .xml format, the field titles will appear as their field
IDs. If the data file is .csv or .asc format, the fields will display with an
appended number, as follows:
<field_title> [1], <field_title> [2], and so forth.
8 Specify how the data in the source file will map to the fields in the destination
form:
!
Map all data file fields to form fields.
!
Map individual data file fields to form fields.
To map all data file fields, click Add All in the AR System Import window.
AR System Import matches data fields to form fields as follows:
!
AR Export or AR XML—Field IDs are matched first, and then field names
are matched for fields without matching IDs.
!
CSV or ASCII—Only field names are matched.
Be aware of the following tips when mapping all data file fields:
!
Ensure that all fields map correctly. If necessary, resolve unmatched or
incorrectly matched fields by mapping those fields individually.
!
If the matching is partially successful, all possible matches are added. To
complete the mapping, map remaining fields individually.
!
If no matches are found and no entries are left in the Form Fields list, an
error is generated. You can delete existing mappings and map fields
individually, or start the import with the partial mapping.
!
If no fields are mapped, an error is generated, and you must load a
mapping or map fields manually.
To map individual data file fields, perform the following steps:
a From the Form Fields list, select the destination field.
b In the Mapping Values section, select Import Fields or Keywords from the
selection menu.
A list of the fields in the data file or a list of keywords will be displayed,
depending on your choice.
c Choose one of the following:
!
From the Import Fields list, select the data field to map to the
destination field that you selected in step 1. The field name appears in
the Mapping Value field.
!
From the Keywords list, select the keyword to map to the destination
field that you selected in step 1. You can also type field names,
keywords, or any constant string into the Mapping Value field.
For example, suppose you select the Create Date field in the Form Fields
list, and you want each record in the destination form to have today’s
date as the value in the Create Date field. You would choose Keywords
as the mapping value, and then choose DATE in the Mapping Values
list. The resulting value in the destination form is the date of the import.
For more information, refer to the Developing AR System Applications:
Basic guide.
d Click Add to create the mapping.
e Repeat these steps for each field to be mapped.
Note: You should map the Request ID field of the destination form. If you
do not map this field, you must set the Duplicate ID preference to
Generate New IDs for All Records, or you will receive errors.
9 Specify default field values, by defining fallback mappings, if desired.
a Choose Mapping > Define Fallback.
The Fallback Mappings dialog box appears, displaying the destination
form fields and a list of keywords.
Figure 8-10: Fallback Mappings Dialog Box
Importing Data ! 209
b From the Form Fields list, select the field for which you want to define a
fallback mapping.
The selected field appears in the Form Field field.
c Choose one or more keywords by doing one of the following:
!
Select a keyword from the Keywords list.
!
Enter a string or keyword into the Fallback Mapping Value field.
!
Enter multiple keywords by separating each value with a space or other
character.
d Click Add.
The mapping is added to the list. You can edit or delete one or more
mappings using the Modify, Delete, and Delete All buttons.
10 Optionally, save the mapping.
a Choose Mapping > Save Mapping.
The Save Mapping dialog box appears, as shown in Figure 8-11 on
page 210.
b Enter a name in the Mapping Name field.
c Enter the mapping directory in the Path field, by selecting a directory from
the list (the AR Path defined in the Desktop preferences), selecting Browse
to choose a directory, or typing a path.
d Optionally, enter a description of the mapping in the Help Text field.
Figure 8-11 on page 210 shows a sample description.
Figure 8-11: Save Mapping Dialog Box
e Optionally, select the Save Log Filename check box.
If you select this box, then the log specified in this procedure is set in
the Import Log File field in the Desktop preferences when you load this
mapping.
f Click OK to create the mapping.
You are now ready to start the import.
11 Choose Import.
A confirmation dialog box appears.
12 Click Yes to start the import.
A status window appears, listing the number of records processed. Each
record in the data file generates a single request in the destination form.
If errors occur, the type of messages you receive depends on the error
handling preferences you set. Refer to Defining Error Handling Preferences on
page 198.
After the import ends, a results message appears and the import log is
updated. You may use your imported data. To inspect the log, refer to Using
the Import Log File on page 212.
Note: You may stop the import before it ends. You are prompted to copy
unprocessed records to the log. There must be enough disk space in
the import log partition to copy the records.
Using a Saved Mapping File
If you have saved a mapping file from a previous import, you can load that
mapping file instead of entering mapping information again.
Mappings save the AR System Import preferences currently set at the time
the mapping is created, so if you load a mapping file, AR System Import will
use the preferences that were set when you saved the mapping file. You can
change preferences as needed and save the mapping file again.
The next time you start AR System Import, the preferences you set for the
application are restored.
AR System Import reads and writes mappings in PC format, with CR LF at
the end of each line.
Using a Saved Mapping File ! 211
Loading a Mapping
1 Choose Mapping > Load Mapping.
The Load Mapping dialog box appears.
Figure 8-12: Load Mapping Dialog Box
2 From the Search Path field, select the directory that contains the mapping.
Selecting All lists all saved mappings and their directories.
3 From the Mappings list, select the mapping.
The directory containing the selected mapping appears in the Mapping Path
field.
4 Click OK.
The mapping is loaded into the Import window, the Fallback Mappings
dialog box, and Preferences dialog box.
Using the Import Log File
AR System Import writes errors to the import log, whether or not you set
error messages to display on screen. The default path is
<ar_home_dir>\arimport.log, however, you may specify another directory
or file name in the preferences. Refer to Defining Desktop Preferences on
page 195.
The import log contains more detail than displayed messages. With AR
Export, CSV, and ASCII file types, failed records are also written intact to the
import log. You can convert the import log to a data file that you can import.
Refer to the following sections for details.
AR XML Data
To write XML (*.xml) data from AR XML records to the import log, you
must use the Alert User with Popup Dialog preference setting, as described
in Defining Error Handling Preferences on page 198. This setting stops the
import and copies the records to the file.
You can inspect the import log file to determine which records caused errors,
and make corrections in the original AR XML data file. You can then import
the corrected AR XML data file. With AR XML files, XML data from the
record is written to the log file, but the structure of the record is not retained
in a way that allows the log file to be converted to an import file.
All Other Data Types
After the import completes, open the import log to identify problems. You
can then either correct the data in the log and convert the log to a data file
that you can import, or correct the original data file and import the file again.
If you edit the original data file, delete any data that was imported
successfully during the original import from the file to avoid creating
duplicate entries.
To import data from the import log, perform the following steps:
1 If the import is not complete, stop the import and copy the remaining
records to the import log.
2 Open the import log (<ar_home_dir>\arimport.log by default).
3 Remove all nondata information (all lines except DATA lines) from the
import log. For CSV and ASCII file types, go to step 5.
4 For AR Export (.arx) file types only: Copy the following lines of code from the
data file to the import log (these lines appear at the beginning of the data file):
FORM, FIELD, FLD-ID, DTYPES
5 Save the edited import log as an AR Export (*.arx) file.
6 Import this AR Export (*.arx) file.
Using the Import Log File ! 213
9
Using Source Control
CHAPTER
This chapter describes how to configure and implement Source
Control (SC) with the AR System. Using a SC system helps you
manage the development of your AR System applications by letting
developers control access to specific system objects. Using a SC system
can prevent developers from overwriting each other’s work by
enforcing check-in and check-out of objects. Finally, source control is
especially important when developers make mistakes and need to
recover earlier versions of a definition, for example, using version
history to recover deleted or modified system objects.
This chapter includes the following information:
!
Integrating Source Control with AR System on page 216
Note: This chapter assumes that you are already familiar with the details of
operating your SC system and that you understand how your SC
database operates. AR System Administrator will not prevent you from
improperly setting up your SC environment, for example, having the
AR System server pointing to different SC projects and different
administrators overwriting each other’s changes. If you have questions
about implementation, refer to the documentation provided with the
SC software.
Using Source Control ! 215
Integrating Source Control with AR System
Be familiar with the details of operating your source control system, and
understand how your source control database operates. AR System
Administrator will not prevent you from improperly setting up your source
control environment; for example, having the AR System server pointing to
different source control projects and different administrators overwriting
each other’s changes. If you have questions about implementation, refer to
the documentation provided with the source control software.
When you integrate source control with AR System, application developers
can quickly see in AR System Administrator if an object is checked out of the
source control database and who its current owner is, as shown in the
following figure.
Figure 9-1: Source Control in AR System (Including Object Properties Dialog Box)
Source control information includes if the object is in source control,
whether it is checked out, the last check-in time, and developer comments, if
any. If developers do not have access to the AR System server or do not have
check-in and check-out privileges in source control, they cannot make
changes to the object.
To view detailed source control information about a server object, select the
object, and choose File > Properties.
216 "Chapter 9—Using Source Control
The Object Properties dialog box appears.
Figure 9-2: Object Properties Dialog Box
Note: You cannot place groups and distributed mappings or pools under
source control. Groups and distributed mappings or pools within AR
System are actually entries inside special forms. Also, You cannot
check extension objects (such as Flashboards objects) into source
control.
Enforced and Advisory Modes
When you integrate your source control software with AR System, you have
the option of defining whether the AR System server is in “enforced” or
“advisory” mode.
If you set the server to Enforced mode, AR System Administrator:
!
Maintains consistency between the AR System server and the source
control database.
!
Prevents accidental changes from taking place.
By contrast, in Advisory mode, AR System does not enforce the links
between the AR System server and the source control database. You run the
risk of allowing discrepancies to creep in between the AR System server and
the source control database. If a discrepancy exists between the server and the
database, AR System will always assume the AR System server is correct.
In Advisory mode, the AR System server and the source control database can
easily get out of synchronization. For example, administrators might:
!
Create API programs that modify objects (for example, disabling an active
link through the driver program).
!
Allow multiple developers in AR System.
Integrating Source Control with AR System ! 217
To update definitions in source control, you can check out every object you
want to update and check in the latest changes. To return to a previous
version of an object stored in source control, get the version you want from
source control, and then import the definition file using the Import in Place
option. For information, refer to Importing Definitions from Source Control
on page 227.
For information about the differences between Enforced and Advisory
modes, see the table Differences Between Enforced and Advisory Modes on
page 221. For information about configuring an AR System server for source
control, refer to the Configuring AR System guide.
Setting Up Source Control with AR System
The following steps provide an overview of how to use source control with
AR System:
1 Install the source control client and server software before integrating it with
AR System Administrator.
Ensure that AR System administrators and AR System application developers
are properly licensed for the source control system you are using. In addition,
make sure the project name is a local directory on their computers. Source
control administrators can set properties like login name and password as
well as specific ones provided by the source control provider. The login name
used by the administrator on the source control system can be different from
that on AR System.
For specific information, refer to your source control application
documentation. Also refer to Displaying User Information in Source Control
on page 235.
2 Configure AR System with the source control database.
After logging in to AR System Administrator, open the Server Information
for the server, and click the Source Control tab.
For a given client machine, administrators will choose available source
control clients from the Provider Name field. You must choose a source
control provider, the level of integration with AR System (Enforced or
Advisory), the fully qualified target directory to the source control database,
and whether check-in and check-out comments are required.
Warning: Do not use source control with a mixed AR System environment.
For example, if you implement source control with AR System,
make sure all developers are using the same versions of AR System.
When accessing the source control database, you will need the login name
and password of the source control client that is used to connect to the source
control database.
Note: If you are integrating with ClearCase source control software, you
must edit the ar.conf (ar.cfg) file as follows:
SCC-Provided-Name: ClearCase
SCC-Target-Dir: <path_to_ClearCase_view>\<ClearCase_VOB>\
<new_directory_name>
SCC-Enabled: 1
For information about the ar.conf (ar.cfg) file, refer to the Configuring AR
System guide.
3 Create a source control project.
To create a project, in the Source Control tab in the Server Information
window, click the Browse button and select a project. The source control
database is a file-based system of.def files. A collection of directories to
store.def object files (for example, forms, filters, and so on) will be created in
the source control database, as shown in the following figure.
Figure 9-3: Source Control Database (Form Definition Files Displayed)
Note: These.def files are text files, not binary files. The.def files are the same
type of files used for importing and exporting definitions of AR
System server objects.
The read-only Project Name field on the Source Control tab shows which
source control database you have selected.
You can use the same settings for all servers that you want to connect to. You
also have the option to enable or disable source control for all servers by
default.
4 After this configuration is complete, you are prompted to log in again to the
AR System server for your changes to occur.
Depending on your source control configuration, when you log in to AR
System Administrator and select a server, you may be prompted to log in to
your source control client as well.
After login is complete, you see that all toolbar buttons and menus in AR
System Administrator for source control integration are enabled.
5 Set the user information so that you can properly check out and check in files.
a In the Server window of AR System Administrator, select the appropriate
server.
b Choose Tools > Source Control > User Information.
The User Info dialog box appears.
c Enter the user name and password.
d Click OK.
6 Add AR System objects to the source control database, except for distributed
mappings and groups.
!
To add one or a few objects to source control, refer to Adding AR System
Objects to Source Control on page 224.
!
To add multiple objects to source control, refer to Exporting Object
Definitions to Source Control on page 225.
7 In AR System Administrator, create, open, or modify server objects as
normal.
Table 9-1: Differences Between Enforced and Advisory Modes
Enforced Mode
Advisory Mode
Creating
Objects
By default, automatically adds Can create objects without
server objects to source control. checking them into source
control. Option provided in Save
dialog box for adding object to
source control.
Opening
Objects
Cannot open objects not in the Can open objects without
checking them out from source
source control database.
control first.
Warning appears that objects
do not exist in source control.
Modifying
Objects
Can modify objects without
Must check out objects from
checking them out from source
source control first before
control first.
modifying them. Otherwise,
warning appears.
If you make any changes to the
object and want to save them,
you can still check out the
object, and save it. However, if
you close the object without
checking it out, no changes are
saved.
8 Save your changes to the objects.
The object is now saved to the AR System server. However, changes to objects
are not updated in source control until you check them in. For more
information about checking objects into source control, refer to Checking in
AR System Objects to Source Control on page 233.
9 Check the objects into source control by selecting them, and clicking the
Check In button (on the source control toolbar in AR System
Administrator).
In Advisory mode, if the object had not been previously checked into the
source control, AR System Administrator will automatically create a version.
You can also check an object back into the source control database without
saving it first, but your changes will not be included in the.def file.
For more information, refer to:
!
Removing AR System Objects from Source Control on page 231
!
Undoing Check Out of AR System Objects in Source Control on page 232
!
Showing the History of AR System Objects in Source Control on page 234
!
Refreshing the Status History in Source Control on page 234
!
Running the Source Control Client Executable on page 236 to learn about
starting the source control client from AR System Administrator.
AR System Source Control Options
The following toolbar buttons and menu items are available in AR System
Administrator for using source control integration with AR System. You can
also access these functions through the Tools menu or by right-clicking an
object in the Server window.
Table 9-6: Source Control Options (Sheet 1 of 2)
Toolbar
Item
Button/Menu
Description
Get Latest Version
page 234
Performs one of the following tasks:
! Writes a version of the most recent AR System
definition file (.def) from source control into a
directory you specify.
! Imports in place the most recent version of the object
into the AR System server.
When you “get” an object, you are merely retrieving a
copy in its latest revised state. The file is not locked from
other system administrators, who in the meantime can
check out and lock the file for their own use.
To “get” an earlier version of an object, use the Show
History function, or use the source control client itself.
Check In
Updates source control with the latest version of the AR page 233
System objects. When you check in an object, the file is
no longer locked, and other system administrators can
use it or modify it.
Check Out
page 231
Copies the latest version of one or more selected AR
System objects from the current project into your
current working folder. When you check out an object,
the file is locked, and no other system administrator can
modify it.
Page
Table 9-6: Source Control Options (Sheet 2 of 2)
Toolbar
Item
Button/Menu
Description
Page
Undo Check Out
page 232
Cancels the Check Out operation and undoes all
changes. You must have a working folder set in your
source control client for this command to work
properly. The file is no longer locked by you, and other
system administrators can check out the file for their
own use. The previous version of the file is retained in
the source control project.
Add To Source
Control
Adds an AR System object (.def file) to the source
control database. The file is archived in the source
control project.
page 224
Remove From
Source Control
Removes.def object files from the source control
database. Removing files from source control does not
remove them from the AR System server.
page 231
Show History
page 234
Displays a list of the past versions of the AR System
objects in your source control project. History reports
summarize information about revisions of the object.
In addition, showing the history of a file gives you the
option of “getting” a copy of the object, in case you
made a mistake and need to revert to an earlier version.
Depending on your source control client, you also can
compare the differences with the current and previous
files (you can perform a “diff”).
Show Differences
Reserved for future use by AR System.
User Info
Displays information about administrators of the
source control database.
page 235
Refresh Status
Refreshes in AR System Administrator the current
information about AR System objects from the source
control database.
page 234
Run Source Control Starts source control client executable to project
Client
directory.
page 236
You can hide or view the source control toolbar by choosing View > Toolbars
> Source Control.
Adding AR System Objects to Source Control
When you enable source control integration with AR System, all subsequent
objects that you create will be added to source control (if the system is in
Enforced mode). However, server objects on existing systems or objects in
Advisory mode will not exist under source control until you add them. Use
this feature to add multiple objects of the same type (for example, forms) into
source control.
To add a large number of objects of different types (for example, forms,
active links, and so on) at the same time into the source control database, use
the Export Definitions to Source Control feature.
Adding AR System Objects to Source Control
1 In the Server window, select one or more AR System objects to add to source
control.
You can use the Shift and Ctrl keys to select multiple objects.
2 Choose Tools > Source Control > Add to Source Control.
The Add to Source Control dialog box appears.
Figure 9-2: Add to Source Control Dialog Box
The Server Window shows that the object has been added to source control.
3 Enter any appropriate comments.
4 Click Add.
The Server Window refreshes to display that the server object has been added
to the source control database. If you open the source control client, you will
also see the object’s.def file added to the source control database.
Exporting AR System Objects into Source Control
You can export a file into source control. The export feature is valuable as a
time-saver, because you can add multiple forms, filters, menus, and so on
into source control as needed, instead of having to add objects into source
control by individual type. The Export dialog box conveniently lets you add
objects into source control all at once. This option allows you to update the
current version of your project in source control by taking a “snapshot” of
the AR System server, which you can then export into your source control
system. The export feature could function for you as a system backup tool to
perform exports of the AR System server, as needed (for example, weekly or
monthly).
Exporting Object Definitions to Source Control
2 Choose Tools > Export Definitions > To Source Control to export
definitions into source control.
Use the Export to Source Control dialog box (Figure 9-3 on page 226) to
select the definitions that you want to export into source control. Definitions
for each object type appear where at least one form, menu, filter, escalation,
active link, application, guide, and packing list has already been created. If
you see a plus (+) next to an object type, this means that at least one object
of that type exists.
All object definitions from the specified server are displayed in the <Objects>
on <server> list. To see a a more detailed list of available objects, click the plus
sign (+) next to each object icon.
Figure 9-3: Export to Source Control Dialog Box
3 Move the objects from the Objects on <server> list to the Objects to Export
list in any of the following ways:
!
Export list.
!
selected type to the Objects to Export list.
!
!
Click Add All to add all the objects to the Objects to Export list.
!
Drag and drop objects between the Objects on <server> and Objects to
Export lists.
!
4 Enter appropriate version information in the Comments box when
exporting definitions into source control.
Depending on how you configured your source control system, comments
are mandatory or optional. For information about Enforced and Advisory
modes and configuring an AR System server for source control, see the
5 Click Export.
Status messages for each server object definition appear as the objects are
added to source control.
6 When the export to source control is finished, click Cancel to close the
Export to Source Control dialog box.
Importing Definitions from Source Control
Importing definitions from source control is especially important for
keeping the AR System server and your source control system synchronized.
For example, an AR System server might contain a version earlier than the
one existing in the source control database, because source control might
have been updated due to changes on the same object from another AR
System server. The administrator should import the newer version into the
AR System server, if necessary.
The options for importing definitions from source control are:
!
To a File—Copies definitions from your source control system into a .def
file. This option is useful for importing new definitions (for example, from
a different system) into your AR System server. First, you would import
the definitions from source control to create a .def file, and then use the
Import Definitions From Definition File feature to copy the definitions
into the AR System server.
!
Import in Place—Imports definitions from source control and overwrites
existing objects on the server. This option is useful for restoring object
definitions if, for example, the AR System server became corrupt and you
wanted to restore them from source control.
Import in Place uses the following process:
!
Checks if the object is available to check out, and imports the object in
place, and checks the object back in to source control.
!
If the object is already checked out by you, the process imports the
object in place, and leaves the object checked out.
!
If the object is checked out to somebody else, you see an error message
for that object, and the process continues for other objects.
Warning: If you use the Import in Place option to import a form definition,
back up the underlying form data first from the old form. The
Import in Place operation first deletes the form definition and the
data, and then it recreates the form on the server. “Importing in
place” might also affect workflow; for example, if active links refer
to fields that no longer exist.
Importing Definitions from Source Control
2 Choose Tools > Import Definitions > From Source Control.
The Import From Source Control dialog box appears.
Figure 9-4: Import From Source Control Dialog Box—Forms
Use this dialog box to select the definitions that you want to import into your
source control system. Definitions for each object type appear where at least
one form, menu, filter, escalation, active link, application, guide, or packing
list has already been created. If you see a plus sign (+) next to an object type,
this means that at least one object of that type exists.
3 Click the appropriate object or objects.
All object definitions are displayed in the Available Objects list. To see a more
detailed list of available objects, click each object icon.
4 Move the objects from the Available Objects list to the Objects to Import list
in any of the following ways:
!
Import list.
!
selected type to the Objects to Import list.
!
!
Click Add All to add all the objects to the Objects to Import list.
!
Drag and drop objects between the Available Objects and Objects to
Import lists.
!
You cannot have two objects with the same name on a single server. If an
object in the import file has the same name as an object on the destination
server, you must take one of the following actions before completing the
import:
!
Remove the object with the same name from the destination server.
!
Rename the object with the same name on the destination server.
To rename an object, select it from the Objects to Import list, click again to
highlight the name, and type a new name.
Warning: If you rename a form in the Import From Source Control dialog
box and then import the newly named form to the destination
server, the form will not retain the connection it had with its
associated workflow on the source server. To maintain the
connection between a renamed form and its associated workflow,
you must rename the form in AR System Administrator before you
create the object definition file. For more information about
renaming forms, refer to the Developing AR System Applications:
Basic guide. If you rename a menu, active link, filter, or escalation
in the Import From Source Control dialog box, you must reattach
it to the appropriate fields on the destination server.
5 As needed, use the Remove button to move the selected objects from the
Object to Import list to the Available Objects list using any of the methods
described in the preceding step.
6 In the Get Mode region, select either Import to a File or Import in Place.
!
Import to a File—Copies the object definitions to a.def or.xml file.
!
Import in Place—Overwrites an existing object with the version from
source control.
7 If you select the Import to a File option, enter a path and.def file name in the
Output field.
You can click Browse to locate a specific.def file, which will be overwritten
with the new information.
8 Click Import to import the definitions to the destination server.
The new definition names are added to the corresponding categories of the
server window. When the import is finished, an Import Complete message
appears.
10 Click Cancel to close the Import Definitions dialog box.
Removing Objects in Source Control
Removing or deleting an object from source control is not the same as
deleting an object from the AR System server.
Deleting an object from the server does not delete it at the same time in the
source control database. This is because the object in source control may be
used by other AR System servers accessing the same source control database.
To delete the object totally, you must remove it from the AR System server
and from the source control database.
If you delete the object from the AR System server but not from source
control, AR System Administrator will add a comment in source control for
the object, stating that the object was deleted in AR System and will specify
the fully qualified path name of the server where the operation was
completed.
If you remove an object from source control that is referenced in a container,
for example, an active link that is used in a guide, the server automatically
removes the reference from the container but does not remove the container.
When you remove an object from source control, you lose the ability to track
the history of any changes made to the object.
Note: Removing an object from source control works differently in Enforced
mode than in Advisory mode. If you remove an object from source
control in Enforced mode, the system still strictly maintains source
control over all AR System objects and will not let you modify them
even if they do not exist in source control. However, Enforced mode
will let you delete objects from the AR System server after they have
been removed from source control.
Removing AR System Objects from Source Control
To remove an object from source control, do the following:
1 In the Server window, select one or more AR System objects to remove from
source control.
2 Choose Tools > Source Control > Remove from Source Control.
A warning message appears, informing you that when removing the object
from the source control database, you will also lose history data.
3 Click OK.
The Server Window refreshes to display that the server object has been
removed from source control.
Checking Objects In and Out of Source Control
The following procedures describe how you check objects in to and out of
source control through AR System Administrator.
Checking Out AR System Objects from Source Control
Use the following steps to check out and lock a file exclusively for your use.
With Enforced mode, other administrators will not be able to modify and
save changes on an object that you have checked out.
1 In the Server window, select one or more AR System objects to check out
from source control.
You can use the Shift and Ctrl keys to select multiple objects.
2 Choose Tools > Source Control > Check Out.
The Check Out from Source Control dialog box appears.
Figure 9-5: Check Out from Source Control Dialog Box
The Server Window lists the user who has checked out the object.
4 Select Check Out Related Objects to include related AR System objects.
This feature is important, for example, if you are modifying an active link
that is attached to a form or a guide. This is because changing workflow in
one place has a “ripple effect” on other related server objects. Simply
changing the name of an active link breaks the workflow with related objects
like forms or guides. Checking out related objects is a useful feature in
avoiding potential conflicts with other system administrators.
5 Click OK.
The Server Window shows what objects are checked out by each user.
Undoing Check Out of AR System Objects in Source Control
Cancelling the Check Out operation leaves the object still checked into the
source control system. In Enforced mode, this means you cannot modify the
object. However, when a check-out is undone, any changes saved to the AR
System server since the last check-in will not be undone. Undoing a
check-out will only clear the Checked Out To object property.
1 In the Server window, select one or more AR System objects that are checked
out from source control.
2 Choose Tools > Source Control > Undo Check Out.
A warning appears.
3 Click Yes (or click Yes All).
The Server Window shows that the server object has not been checked out to
you.
Checking in AR System Objects to Source Control
After you have modified an object and saved it, use the following procedure
to check it back in to the source control database.
1 In the Server window, select one or more AR System objects to check in to
source control.
2 Choose Tools > Source Control > Check In.
The Check In to Source Control dialog box appears.
Figure 9-6: Check In to Source Control Dialog Box
4 Click Keep Checked Out to update the object in the source control system
but keep it checked out.
In Enforced mode, the system will check the object into the source control
database, and then immediately check it back out, all as one operation. This
feature is useful because the object is still locked for you, and no other
administrators will be able to modify it.
5 Click OK.
The Server Window shows that the server object has been checked in to the
source control database, that is, unless you kept the object checked out.
Viewing History in Source Control
Administrators can also look at the history of a given object in source control,
update the source control status on the server window, or undo a check out
from the source control. When you undo a check-out, any changes saved to
the AR System server since the last check-in will not be undone.
Showing the History of AR System Objects in Source Control
Use the following procedure to view the history of objects (the comments
system administrators add over the history of the object) in the source
control database.
1 In the Server window, select one or more AR System objects you want to
check.
2 Choose Tools > Source Control > Show History.
The History Options dialog box for your source control software appears.
3 Define the history information, as appropriate.
Refreshing the Status History in Source Control
Refreshing the status list in AR System Administrator is especially useful for
ensuring that:
!
Your.def files were added to the source control database.
!
You have the latest version of the.def files.
!
Another developer does not have the file checked out.
To refresh the status in the file list, use the following procedure:
1 In the Server window, select one or more AR System objects for the status you
want to refresh.
2 Choose Tools > Source Control > Refresh Status.
The information in the AR System server will be refreshed from the source
control database.
Other Source Control Tasks
The following procedures describe other source control tasks you can
accomplish with AR System Administrator.
Getting the Latest Version of AR System Objects from Source Control
Getting the latest version of an object copies the most recent version of the
object from the source control database into the AR System server, or creates
a copy in a location you specify.
1 In the Server window, select one or more AR System objects whose latest
version you want to get from source control.
2 Choose Tools > Source Control > Get Latest Version.
The Get from Source Control dialog box appears.
Figure 9-7: Get from Source Control Dialog Box
3 Perform one of the following steps:
!
To copy the object definition into a .def file, select Write to a file, and click
the Browse button (...) to select a file location.
!
To copy (and overwrite) a server object from source control into the AR
System server, select Import In Place (the default). To copy a large number
of objects from source control into the AR System server, refer to
Importing Definitions from Source Control on page 227.
4 Click OK.
The object’s .def file is copied into your working directory.
Displaying User Information in Source Control
Use the following procedure to display user information and source control
options about the user.
1 In the Server window, select a server for the user information you want to
display.
2 Choose Tools > Source Control > User Information.
The User Info dialog box appears.
3 Enter the user name and password.
4 Click Advanced Properties to define general options for the source control
project.
The source control options that appear display the properties you can set for
the selected project.
5 Click OK.
Note: To avoid security issues if multiple users are using the same SourceSafe
and AR System Administrator clients, or if there is a problem logging
in to SourceSafe, remove the SSDIR and SSUSER environmental
variable settings from the Environment tab in the System Properties
dialog box in the MS Windows Control Panel.
Running the Source Control Client Executable
You can launch the source control client from AR System Administrator.
This feature might be necessary and useful in some source control
environments that support multiple check-outs and merges.
1 Choose Tools > Source Control > Run Source Control Client to open the
source control client for the project.
2 Return to AR System Administrator, as needed.
10
Server Events Form
CHAPTER
The Server Events form enables you to capture server-related activities
and use them in workflow and API programs. You can select the server
events that you want to record, search and view the returned entries,
and create workflow to notify companion servers and interested
clients of server changes that may affect them.
The following topics are covered in this chapter:
!
Understanding the Server Events Form on page 238
!
Using Server Events in Workflow on page 253
For information about setting Server Event options, refer to the
Server Events Form ! 237
Understanding the Server Events Form
The Server Events form captures the server changes that you record. The
Server Events form enables you to notify other servers of cache changes if
multiple servers are sharing the same database, it can also notify interested
clients of cache changes and user or group events. For more information, see
Using Server Events in Workflow on page 253.
The options on the Server Events tab of the Server Information dialog box
enable you to specify what activities you want to record to the form. For more
information on selecting Server Events options, refer to the Configuring AR
System guide.
The Server Events form is similar to other AR System forms. You can add
additional fields and workflow to it, but you cannot delete the four reserved
fields, which are discussed in the following section.
How the Form Is Created
The Server Events form is created automatically by the server and contains
five reserved fields:
800
! 801
! 802
!
!
803
!
804
AR_RESERV_SVR_EVENT_TYPE
AR_RESERV_SVR_EVENT_CAUSE
AR_RESERV_SVR_EVENT_DETAILS
_1
_2
_3
These five fields distinguish the Server Events form from all other forms.
There can be only one Server Events form in the AR System database;
therefore, only one form contains the five reserved fields specific to the Server
Events form: 800, 801, 802, 803, 804.
238 "Chapter 10—Server Events Form
There are two primary instances in which a Server Events form can be
created.
!
Case 1: When the server starts, the server will create the Server Events form
automatically if the form does not already exist in the AR System database.
If you delete the Server Events form, the server will automatically
regenerate the form the next time the server is started.
!
Case 2: If you create your own Server Events form, you will need to supply
default values with the correct data type for the required core fields. If the
Server Events form already exists and you try to create a form with the four
reserved fields, the server will return an error when you try to save the
form. Error checking will not allow the existence of more than one Server
Events form.
Similar to the distributed mapping forms, the Server Events form can be
viewed and modified using AR System Administrator or driver. You can also
rename the Server Events form. However, if any of the five reserved fields are
removed, the form will no longer be a Server Events form.
Types of Events You Can Record
Twelve types of server events can be recorded; the first nine are server object
changes and the last three are user, group, and server-setting changes
respectively.
Server Event Types
The #define statements for the event types in ar.h are:
#define AR_SVR_EVENT_CHG_SCHEMA
#define AR_SVR_EVENT_CHG_FIELD
#define
AR_SVR_EVENT_CHG_CHARMENU
#define AR_SVR_EVENT_CHG_FILTER
#define AR_SVR_EVENT_CHG_IMPORT
#define AR_SVR_EVENT_CHG_ACTLINK
#define AR_SVR_EVENT_CHG_ESCAL
#define AR_SVR_EVENT_CHG_VUI
#define
AR_SVR_EVENT_CHG_CONTAINER
1
2
3
4
5
6
7
8
9
Understanding the Server Events Form ! 239
#define AR_SVR_EVENT_CHG_USERS
#define AR_SVR_EVENT_CHG_GROUPS
#define
AR_SVR_EVENT_CHG_SVR_SETTINGS
10
11
12
These numbers are meaningful when you are viewing the events recorded in
the Server Events form. For more information, see Viewing the Server
Changes You Recorded on page 242.
Server Object Changes
Server object changes are changes to forms, filters, active links, escalations,
fields, VUIs, char menus, and containers. The AR System server will record
the API calls that caused the server object change. The AR System server will
record the server object change event type into the Event Type field and the
RPC call number of the API call in the Cause field. The information recorded
in the Event Details field depends on the server object. For example, when a
form is modified, the form name is recorded in the Event Details field. For a
complete listing of what is recorded in the Event Details field as well as the
API calls that are recorded based on corresponding event types and causes,
see the Table 10-1 on page 243.
User/Group Changes
When users or groups are added, modified, or deleted, an event is logged in
the Server Events form.
For user changes, the user change event type is logged in the Event Type field,
the event cause (user added, modified, or deleted) is logged in the Event
Cause field, and the entry ID and name of the user is recorded in the Event
Details field.
For group changes, the group change event type is recorded in the Event
Type field, the event cause (group added, modified, or deleted) is recorded in
the Event Cause field, and the entry ID and name of the group is recorded in
the Event Details field.
For a complete listing of what is recorded in the Event Details field as well as
the API calls that are recorded based on the corresponding event type and
causes, see the Table User and Group Changes on page 246.
User and group changes are recorded in the following cases:
!
User added, modified, or deleted using the User or Group form
!
User or group changes using the arcache utility
!
User or group changes using the arreload utility
Server Setting Changes
All changes to server configurations are logged in the Server Events form. The
server settings change event will be recorded in the Event Type field. The
numeric value of the server option (AR_SERV_INFO_XX) will be recorded in
the Event Cause field. (For more information about the different
AR_SERV_INFO_XX options, see the AR System C API Reference Guide.) The
datatype and value of the input argument to the SetServerInfo call will be
recorded in the Event Details field. For server options that configure
passwords, the password will be replaced by an arbitrary number of asterisks
for security purposes.
For a complete listing of what is recorded in the Event Details field as well as
the API calls that are recorded based on the corresponding event type and
causes, see the Table 10-1 on page 243.
Viewing the Server Changes You Recorded
When you open the Server Events form in AR System Windows User Tool to
search or view the entries that have been recorded, you will see numbers and
raw data in the fields. You will not see textual descriptions explaining the data
returned for each of the four reserved fields. For example, if you recorded the
server events associated with adding a new user, a search on the Server Events
form will look similar to the screen in the following figure.
Figure 10-8: Adding a User
Only the numeric values for Event Type and Event Cause are returned, and
only a brief description is provided in the Event Details field. Use the tables
that follow to look up the description that corresponds to the type number
and cause number of the server event for which you need information.
Viewing Server Object Changes
For object changes, the event type can be 1 through 9 depending on the type
of object change being recorded. The following information appears in the
fields on the Server Events form when an object change is recorded:
!
Event Type: 1 to 9
!
Event Cause: RPC call number of the API call
!
Event Details 1: Contents depend on the server object being recorded
!
!
!
Request ID: The unique number assigned to identify the entry
!
Event Date: Time and date that the event occurred
!
Submitter: User who caused the server object event
In the Event Details 1 field, the object names recorded for the Set calls are the
names of the objects before the Set operation. Therefore, if an ARSetSchema
call renames the form from AA to BB, AA will be the form name recorded in
the Event Details field for the server event.
For “Set” API calls, if the name of the object is changed, the Event Details 2
field will contain the old name of the object, and the Event Details 1 field will
contain the new name. If the name is not changed by the Set call, the Event
Details 2 field will contain a NULL datatype
In the Event Details fields, semicolons separate multiple items. There are no
spaces after the semicolon, and the spaces after the semicolon in the table
below were added for display clarity. The string recorded in the Event Details
fields can have maximum lengths of 255 bytes
(AR_MAX_SVR_EVENT_DETAILS), not including the NULL. If the value to
record in the Event Details fields exceed the maximum, the value will be
truncated.
Table 10-1: Server Object Changes (Sheet 1 of 3)
Type
Cause
Cause
Description
Event Details 1
Event Details 2
1
8
ARSetSchema
form (or schema)
name
1
9
ARCreateSchema
form (or schema)
name
Event Details 3
old form (or
schema) name
Type
Cause
Cause
Description
Event Details 1
1
10
ARDeleteSchema
form (or schema)
name
2
13
ARSetField
field ID; field name form (or schema)
name
2
14
ARCreateField
name
2
43
ARDeleteField
name
2
56
ARDeleteMultiple
Fields
field ID; field
ID;…; field ID
3
17
ARSetCharMenu
menu name
3
18
ARCreateCharMenu
menu name
3
19
ARDeleteCharMenu
menu name
4
22
ARSetFilter
filter name
4
23
ARCreateFilter
filter name
4
24
ARDeleteFilter
filter name
5
35
ARImport
6
39
ARSetActiveLink
active link name
6
40
ARCreateActiveLink
active link name
6
41
ARDeleteActiveLink
active link name
7
49
ARSetEscalation
escalation name
7
50
ARCreateEscalation
escalation name
7
51
ARDeleteEscalation
escalation name
8
63
ARSetVUI
vui ID; vui name
form (or schema)
name
8
64
ARCreateVUI
vui ID; vui name
form (or schema)
name
Event Details 2
Event Details 3
old field name
old menu name
old filter name
old active link
name
old escalation
name
old vui name
Type
Cause
Cause
Description
Event Details 1
Event Details 2
8
65
ARDeleteVUI
vui ID; vui name
form (or schema)
name
9
75
ARSetContainer
container name
9
76
ARCreateContainer
container name
9
77
ARDeleteContainer
container name
Event Details 3
old container
name
Viewing User Changes
For user changes, the event type will always be 10. The following information
appears in the fields on the Server Events form when a user change is
recorded:
!
Event Type: 10
!
Event Cause: User added (0), modified (1), or deleted (2)
!
Event Details 1: Entry ID of the user and the user login name
!
Event Details 2: Unused
!
!
Request ID: The unique number assigned to identify a particular request
!
!
Submitter: User who caused the user change event
Viewing Group Changes
For group changes, the event type will always be 11. The following
information appears in the fields on the Server Events form when a group
change is recorded:
!
Event Type: 11
!
Event Cause: Group added (0), modified(1), or deleted(2)
!
Event Details 1: Entry ID of the group and the group name
!
!
!
!
!
Submitter: User who caused the group change event
On the User form, the value in the Event Details 1 field for the user login
name is the value that is in reserved Field 101. For the Group form, the value
for the group name is the value that is in reserved Field 105.
When the user login name or group name is modified, the name recorded in
the Event Details 1 field is the name after it is modified. For example, if an
ARSetEntry is called to change the user’s login name from YY to ZZ, ZZ will
be recorded as the user’s login name in the Event Details 1 field.
spaces after the semicolon, and the spaces after the semicolon in the table
below were added for display clarity.
Table 10-2: User and Group Changes
Type
Cause
Cause Description
Event Details 1
10
0
User added
entry ID; user login name
10
1
User modified
10
2
User deleted
11
0
Group added
entry ID; group name
11
1
Group modified
11
2
Group deleted
Viewing Server Setting Changes
For server setting changes, the event type will always be 12. The following
information appears in the fields on the Server Events form when a server
setting change is recorded:
!
Event Type: 12
!
Event Cause: The numeric value of the server option AR_SVR_INFO_XX
!
Event Details 1: The input datatype and input value to the SetServerInfo
call
!
!
!
!
!
Submitter: User who called SetServerInfo
For the following server options, the input password will be replaced with an
arbitrary number of asterisks before storing it in the Event Details 1 field:
AR_SERVER_INFO_DB_PASSWORD,
AR_SERVER_INFO_DSO_USER_PASSWD,
AR_SERVER_INFO_DSO_TARGET_PASSWD,
AR_SERVER_INFO_APP_SERVICE_PASSWD,
AR_SERVER_INFO_MID_TIER_PASSWD,
AR_SERVER_INFO_PLUGIN_PASSWD,
AR_SERVER_INFO_PLUGIN_TARGET_PASSWD
The datatype is included in the Event Details 1 field because
AR_DATA_TYPE_NULL will not have a value, only the datatype.
spaces after the semicolon, and the spaces after the semicolon in the
following table were added for display clarity.
An AR Import API call can result in many server object changes, but this
event will be recorded as one server event. Therefore, even though one
Import call can add or modify several forms, filters, active links, etc., the
server will record these changes as an Import object change event, and the
Cause field will contain the RPC call number of ARImport.
Table 10-3: Server Setting Changes (Sheet 1 of 6)
Type
Cause
Cause Description
Event Details 1
12
5
AR_SERVER_INFO_ALLOW_GUESTS
datatype; value
12
6
AR_SERVER_INFO_USE_ETC_PASSWD
datatype; value
12
7
AR_SERVER_INFO_XREF_PASSWORDS
datatype; value
12
8
AR_SERVER_INFO_DEBUG_MODE
datatype; value
Type
Cause
Cause Description
Event Details 1
12
10
AR_SERVER_INFO_DB_PASSWORD
datatype; value
12
15
AR_SERVER_INFO_SET_PROC_TIME
datatype; value
12
16
AR_SERVER_INFO_EMAIL_FROM
datatype; value
12
17
AR_SERVER_INFO_SQL_LOG_FILE
datatype; value
12
18
AR_SERVER_INFO_FLOAT_TIMEOUT
datatype; value
12
20
AR_SERVER_INFO_UNQUAL_QUERIES
datatype; value
12
21
AR_SERVER_INFO_FILTER_LOG_FILE
datatype; value
12
22
AR_SERVER_INFO_USER_LOG_FILE
datatype; value
12
28
AR_SERVER_INFO_MAX_ENTRIES
datatype; value
12
31
AR_SERVER_INFO_ESCALATION_LOG_
FILE
datatype; value
12
33
AR_SERVER_INFO_SUBMITTER_MODE
datatype; value
12
34
AR_SERVER_INFO_API_LOG_FILE
datatype; value
12
37
AR_SERVER_INFO_FTEXT_TIMEOUT
datatype; value
12
45
AR_SERVER_INFO_DS_RPC_SOCKET
datatype; value
12
46
AR_SERVER_INFO_DS_LOG_FILE
datatype; value
12
47
AR_SERVER_INFO_SUPPRESS_WARN
datatype; value
12
50
AR_SERVER_INFO_SAVE_LOGIN
datatype; value
12
57
AR_SERVER_INFO_CACHE_LOG_FILE
datatype; value
12
59
AR_SERVER_INFO_THREAD_LOG_FILE
datatype; value
12
65
AR_SERVER_INFO_TCD_TCP_PORT
datatype; value
12
66
AR_SERVER_INFO_DSO_DEST_PORT
datatype; value
12
78
AR_SERVER_INFO_NFY_TCP_PORT
datatype; value
12
79
AR_SERVER_INFO_FILT_MAX_TOTAL
datatype; value
12
80
AR_SERVER_INFO_FILT_MAX_STACK
datatype; value
12
81
AR_SERVER_INFO_DEFAULT_ORDER_BY
datatype; value
Type
Cause
Cause Description
Event Details 1
12
82
AR_SERVER_INFO_DELAYED_CACHE
datatype; value
12
83
AR_SERVER_INFO_DSO_MERGE_STYLE
datatype; value
12
84
AR_SERVER_INFO_EMAIL_LINE_LEN
datatype; value
12
85
AR_SERVER_INFO_EMAIL_SYSTEM
datatype; value
12
86
AR_SERVER_INFO_INFORMIX_RELAY_MOD
datatype; value
12
87
AR_SERVER_INFO_PS_RPC_SOCKET
datatype; value
12
88
AR_SERVER_INFO_REGISTER_
PORTMAPPER
datatype; value
12
89
AR_SERVER_INFO_SERVER_NAME
datatype; value
12
90
AR_SERVER_INFO_DBCONF
datatype; value
12
92
AR_SERVER_INFO_AP_RPC_SOCKET
datatype; value
12
93
AR_SERVER_INFO_AP_LOG_FILE
datatype; value
12
94
AR_SERVER_INFO_AP_DEFN_CHECK
datatype; value
12
95
AR_SERVER_INFO_MAX_LOG_FILE_SIZE
datatype; value
12
96
AR_SERVER_INFO_CLUSTERED_INDEX
datatype; value
12
97
AR_SERVER_INFO_ACTLINK_DIR
datatype; value
12
98
AR_SERVER_INFO_ACTLINK_SHELL
datatype; value
12
99
AR_SERVER_INFO_USER_CACHE_UTILS
datatype; value
12
100
AR_SERVER_INFO_EMAIL_TIMEOUT
datatype; value
12
102
AR_SERVER_INFO_ENCRYPT_AL_SQL
datatype; value
12
103
AR_SERVER_INFO_SCC_ENABLED
datatype; value
12
104
AR_SERVER_INFO_SCC_PROVIDER_NAME
datatype; value
12
105
AR_SERVER_INFO_SCC_TARGET_DIR
datatype; value
12
106
AR_SERVER_INFO_SCC_COMMENT_
CHECKIN
datatype; value
12
107
AR_SERVER_INFO_SCC_COMMENT_
CHECKOUT
datatype; value
Type
Cause
Cause Description
Event Details 1
12
108
AR_SERVER_INFO_SCC_INTEGRATION_
MODE
datatype; value
12
109
AR_SERVER_INFO_EA_RPC_SOCKET
datatype; value
12
110
AR_SERVER_INFO_EA_RPC_TIMEOUT
datatype; value
12
111
AR_SERVER_INFO_USER_INFO_LISTS
datatype; value
12
112
AR_SERVER_INFO_USER_INST_TIMEOUT
datatype; value
12
113
AR_SERVER_INFO_DEBUG_GROUPID
datatype; value
12
115
AR_SERVER_INFO_EA_SYNC_TIMEOUT
datatype; value
12
114
AR_SERVER_INFO_APPLICATION_AUDIT
datatype; value
12
117
AR_SERVER_INFO_SVR_SEC_CACHE
datatype; value
12
118
AR_SERVER_INFO_LOGFILE_APPEND
datatype; value
12
119
AR_SERVER_INFO_MINIMUM_API_VER
datatype; value
12
120
AR_SERVER_INFO_MAX_AUDIT_LOG_FILE_SIZE datatype; value
12
121
AR_SERVER_INFO_CANCEL_QUERY
datatype; value
12
122
AR_SERVER_INFO_MULT_ASSIGN_GROUPS
datatype; value
12
123
AR_SERVER_INFO_ARFORK_LOG_FILE
datatype; value
12
124
AR_SERVER_INFO_DSO_PLACEHOLDER_
MODE
datatype; value
12
126
AR_SERVER_INFO_DSO_SOURCE_SERVER
datatype; value
12
125
AR_SERVER_INFO_DSO_POLLING_
INTERVAL
datatype; value
12
128
AR_SERVER_INFO_DSO_TIMEOUT_NORMAL
datatype; value
12
130
AR_SERVER_INFO_ENC_DATA_KEY_EXP
datatype; value
12
131
AR_SERVER_INFO_ENC_PUB_KEY_EXP
datatype; value
12
133
AR_SERVER_INFO_ENC_SEC_POLICY
datatype; value
12
134
AR_SERVER_INFO_ENC_SESS_H_ENTRIES
datatype; value
12
132
AR_SERVER_INFO_ENC_DATA_ENCR_ALG
datatype; value
Type
Cause
Cause Description
Event Details 1
12
135
AR_SERVER_INFO_DSO_TARGET_
CONNECTION
datatype; value
12
137
AR_SERVER_INFO_ORACLE_QUERY_ON_
CLOB
datatype; value
12
140
AR_SERVER_INFO_LOCALIZED_SERVER
datatype; value
12
141
AR_SERVER_INFO_SVR_EVENT_LIST
datatype; value
12
142
AR_SERVER_INFO_DISABLE_ADMIN_
OPERATIONS
datatype; value
12
143
AR_SERVER_INFO_DISABLE_
ESCALATIONS
datatype; value
12
144
AR_SERVER_INFO_ALERT_LOG_FILE
datatype; value
12
145
AR_SERVER_INFO_DISABLE_ALERTS
datatype; value
12
146
AR_SERVER_INFO_CHECK_ALERT_USERS
datatype; value
12
147
AR_SERVER_INFO_ALERT_SEND_TIMEOUT
datatype; value
12
148
AR_SERVER_INFO_ALERT_OUTBOUND_
PORT
datatype; value
12
149
AR_SERVER_INFO_ALERT_SOURCE_AR
datatype; value
12
150
AR_SERVER_INFO_ALERT_SOURCE_FB
datatype; value
12
151
AR_SERVER_INFO_DSO_USER_PASSWD
datatype; value
12
152
AR_SERVER_INFO_DSO_TARGET_PASSWD
datatype; value
12
153
AR_SERVER_INFO_APP_SERVICE_PASSWD
datatype; value
12
154
AR_SERVER_INFO_MID_TIER_PASSWD
datatype; value
12
155
AR_SERVER_INFO_PLUGIN_LOG_FILE
datatype; value
12
156
AR_SERVER_INFO_SVR_STATS_REC_MODE
datatype; value
12
157
AR_SERVER_INFO_SVR_STATS_REC_
INTERVAL
datatype; value
12
158
AR_SERVER_INFO_DEFAULT_WEB_PATH
datatype; value
Type
Cause
Cause Description
Event Details 1
12
159
AR_SERVER_INFO_FILTER_API_RPC_
TIMEOUT
datatype; value
12
160
AR_SERVER_INFO_DISABLED_CLIENT
datatype; value
12
161
AR_SERVER_INFO_PLUGIN_PASSWD
datatype; value
12
162
AR_SERVER_INFO_PLUGIN_ALIAS
datatype; value
12
163
AR_SERVER_INFO_PLUGIN_TARGET_
PASSWD
datatype; value
12
164
AR_SERVER_INFO_REM_WKFLW_PASSWD
datatype; value
12
165
AR_SERVER_INFO_REM_WKFLW_TARGET_
PASSWD
datatype; value
12
166
AR_SERVER_INFO_EXPORT_SVR_OPS
datatype; value
12
167
AR_SERVER_INFO_INIT_FORM
datatype; value
12
168
AR_SERVER_INFO_ENC_PUB_KEY_ALG
datatype; value
12
169
AR_SERVER_INFO_IP_NAMES
datatype; value
12
170
AR_SERVER_INFO_DSO_CACHE_CHK_
INTERVAL
datatype; value
12
171
AR_SERVER_INFO_DSO_MARK_PENDING_
RETRY
datatype; value
12
172
AR_SERVER_INFO_DSO_RPCPROG_NUM
datatype; value
Datatypes Values
The following are datatype values for the Server Events form. For Example,
for server setting changes, the Event Details 1 field records the datatype and
value. The datatype is recorded as 0, 2, and 4, corresponding to the datatypes
in the following table.
Table 10-4: Datatype Values
Datatype
Description
#define in ar.h
0
NULL
AR_DATA_TYPE_NULL
2
Integer
AR_DATA_TYPE_INTEGER
4
Character String
AR_DATA_TYPE_CHAR
Using Server Events in Workflow
Recording server events enables you to communicate internal (non-data)
server changes to processes outside the server and to use workflow to notify
companion servers or interested clients of changes that affect them.
You can create workflow that will be triggered when a server event is
recorded. For example, you may want to create a filter that fires when an
entry is submitted to the Server Events form indicating that an object change
has occurred. The filter should execute a Run Process action that runs the
arsignal program to force a companion AR System server to reload its cache.
The filter should have one such action for each companion server.
So, if you wanted to make server “foo” reload its cache, you would construct
the filter run process action as follows:
arsignal -g foo
If foo were running on specific port 2033, then the action would be
constructed as follows:
arsignal -g foo:2033
For more information about arsignal, refer to the Configuring AR System
guide.
Using Server Events in Workflow ! 253
11
Defining Packing Lists
CHAPTER
Packing lists are functional units that contain an
administrator-defined grouping of information. For example, if an
application contains ten forms, each form and its related workflow can
be organized in its own functional unit, or packing list. Each of these
units can be added to the application’s packing list. Another
application can add these packing lists to reuse functional units from
the preceding application. Packing lists offer the administrator a
method of grouping and organizing large amounts of information to
make development simpler. This eases the transition from
development to production. This chapter explains how to create and
use packing lists for your applications.
!
Using Packing Lists on page 256
!
Creating Packing Lists on page 256
!
Working in the Packing List Window on page 257
!
Saving Packing Lists in XML on page 262
Defining Packing Lists ! 255
Using Packing Lists
Administrators can use packing lists within workspaces. Normally, the
administrator works within the context of all the objects on the server. By
grouping relevant objects in a packing list, the administrator may choose to
work within the context of a defined packing list. In workspace mode, only
objects belonging to the selected packing list are visible. New objects
automatically become members of the packing list, and objects may be
optionally removed from the packing list without being deleted. Objects can
belong to multiple packing lists, so they can be visible in more than one
workspace. For more information about workspaces, refer to the Developing
AR System Applications: Basic guide.
Administrators can construct a packing list to create and apply external
utilities, such as installation utilities or external object browsers. In addition,
administrators can use packing lists to gather information on specified
objects and manipulate those objects.
Packing lists can contain other packing lists. You can also store packing lists
through Source Code Control integration. For more information, refer to
Integrating Source Control with AR System on page 216.
If you use the Distributed Server Option (DSO), you cannot track DSO
mappings that have been renamed. Packing lists can track only server objects
with database IDs. DSO mappings are not server objects, so they are not
tracked by their database ID, but by their actual name. Therefore, if you
change a DSO mapping’s name and then open a packing list that contained
that mapping, the DSO mapping will be missing from the packing list.
Creating Packing Lists
Use the following procedure to create a packing list.
Creating Packing Lists
1 In AR System Administrator, select a server to administer.
2 Choose File > New Server Object.
3 Select Packing List, and click OK.
The Create Packing List window appears.
256 "Chapter 11—Defining Packing Lists
4 Specify the application basic criteria. (See Specifying Packing List Basics on
page 259.)
5 Specify the application permissions. (See Defining Packing List Permissions on
page 261.)
6 Specify application subadministrator permissions. (See Defining
Subadministrator Permissions for Packing Lists on page 261.)
7 Define change history. (Refer to the Developing AR System Applications: Basic
guide.)
8 Define help text. (See Creating AR System Administrator Help for Packing Lists
on page 261 and the Developing AR System Applications: Basic guide.)
Working in the Packing List Window
Use the Packing List (Figure 11-9 on page 258) window to create and modify
packing lists. This section describes how to work with the tabs in this
window.
Working in the Packing List Window ! 257
Note: In this chapter, Packing List window refers to a Create Packing List or
Modify Packing List window.
Figure 11-9: Packing List Window
You can open multiple windows to create or modify the packing lists that you
have permission to administer.
Use the following tabs in the Packing List window to define parameters:
Basic
Defines the basic properties of the packing list and the list
of system objects needed to create a packing list.
Permissions
Defines which access control groups can access the
packing list.
Subadministrator
Permissions
Defines which access control groups have
subadministrator permissions for the packing list.
Change History
Records the owner of a packing list, 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 packing list. In most cases, this
help text is a description of the packing list, what it does,
and how it is used.
Specifying Packing List Basics
The following section describes how to fill in the Basic tab of the Packing List
window in Figure 11-9 on page 258.
Use the following procedure to define packing list basics.
Defining Packing List Basics
1 Create a packing list or open the packing list with which you want to work.
The Available Objects list displays all AR System objects defined on the
server.
2 Enter or update a name in the Name field.
Packing list names must be unique on each AR System server. Although there
are no naming conventions, create names that are descriptive and indicative
of the packing list’s usage. Names can be a maximum of 80 characters,
including spaces. Names can include double-byte characters, but avoid using
numbers at the beginning of the name.
Names are shared across packing lists, active link guides, filter guides, web
services, and applications, so each name must be unique.
3 Enter a label in the Label field.
Although there are no naming conventions, create labels that are descriptive
and indicative of the packing list’s usage. Labels can be a maximum of 255
bytes, including spaces.
4 Enter a description of the packing list in the Description field (optional).
You can enter a maximum of 2000 bytes.
5 Move items from the Available Objects list to the Packing List Objects list in
any of the following ways:
!
Select the available objects and click Add to add objects to the Packing List
Objects list.
!
Select the object type and click Add to add all objects of a specific type to
the Packing List Objects list.
!
Use the context menu to Add objects.
!
Drag and drop objects between Available Objects and Packing List Objects
list.
!
Use the Add Related - All button (or right-click option) to move an object
and its related objects. To drag and drop the objects instead, hold down the
Shift key while dragging.
6 Use the Add Related - Restrict button (or right-click option) to limit the
scope of server objects when selecting shared workflow to add to the packing
list. This option defines new rules for each workflow object, establishing
parameters that restrict the objects that will be related to include only the
associations defined by the new rules (see table that follows) for each type of
workflow.
Each of the object definitions defined in the table below are included in the
packing list as follows when you use the Add Related - Restrict button.
For:
Packing List Includes:
Forms
All related menus, active links, filters, escalations, active
mapping definitions. In addition, menus from the
Change Field action of the active links will be included.
Any other forms referenced in workflow actions, guides,
and menus will not be associated as related objects.
Join forms
All forms that were used to create these join forms as
well as their related items (as defined in the operations
included in the Forms above).
Active links
All menus that are referenced in the Change Field
actions, and all guides that are referenced in the Call
Guide action. The guides should refer to the same form
to which the active link refers. The active links that are
referenced in the guide also fall within the same scope;
therefore, the associated objects of those active links will
be included. This cycle continues until it reaches a form.
Filters
All filter guides referenced in a Call Guide action and all
DSO mapping definitions referenced in a DSO action.
Filters that are referenced in the guide also fall within the
same scope; therefore, the associated objects of those
filters will be included. The guides should refer to the
same form to which the filter refers. Escalations do not
have any of the above actions, so there will be no
associations for escalations.
Active link guides
All active links referenced in the guide as well as all
associated objects for those active links.
For:
Packing List Includes:
Filter guides
All filters referenced in the guide as well as all associated
objects for those filters.
Applications
All associated forms and the list of related objects
associated with those forms.
Web Services
Included as an independent object.
Menus
No related items included.
Flashboards
Included as an independent object.
7 Use any of the methods in step 5 and the Remove button to move the selected
objects from the Packing List Objects list to the Available Objects list.
You can now open the packing list as a workspace or save it in XML. For
more information about workspaces, refer to the Developing AR System
Defining Packing List Permissions
Use the Permissions tab to determine which access control groups can
display the application in AR System Windows User Tool.
Defining Subadministrator Permissions for Packing Lists
Use the Subadministrator Permissions tab to define subadministrator
permissions for access control groups.
Building and Using Packing List Change History
AR System automatically records the owner of a packing list, the user who
last modified the packing list, and the date of the modification. To display or
add to this information, click the Change History tab in the Packing List
window.
Creating AR System Administrator Help for Packing Lists
To create help text for a packing list, click the Help Text tab in the Packing
List window. In most cases, the help text that you enter is a description of the
packing list, what it does, and how it is used. Only administrators and
subadministrators can view and edit packing list help text.
For more information subadministration, permissions, creating help text,
and on how to build and use change history, refer to the Developing AR
Saving Packing Lists in XML
You can save packing lists in XML format on the administrator’s local
machine or on the network. When you save a packing list externally, the AR
System server converts its format to XML. In XML format, the group of
objects in a packing list contain important header information for easy
parsing. The header consists of the packing list’s name, server, and object
property information, as the following example shows.
<?xml version="1.0"?>

<packinglist name="Help Desk" label="Help Desk Application" version="1.0">
<description>all forms and workflow used for Help Desk
Application</description>
<forms-list>
<forms name="Help Desk" server="ACME.COM">
</forms>
</forms-list>
<active-links-list>
<active-links name="Help Desk Active Link" server="ACME.COM">
</active-links>
</active-links-list>
<filters-list>
<filters name="Help Desk Filter" server="ACME.COM">
</filters>
</filters-list>
<escalations-list>
</escalations-list>
<guides-list>
</guides-list>
<applications-list>
</applications-list>
<packing-lists-list>
</packing-lists-list>
<menus-list>
</menus-list>
<groups-list>
</groups-list>
<distributed-mappings-list>
</distributed-mappings-list>
</packinglist>
Use the following procedure to save a packing list in XML format.
Saving a Packing List in XML Format
1 Create and save a packing list.
2 Choose Packing List > Generate XML to open the Save Packing List dialog
box.
3 Specify where you want the packing list saved.
4 Type a name for the file in the File Name field.
5 Click Save.
The AR System server stores all selected definitions in a single file. If you
specify an existing file name, a dialog box appears and prompts you to replace
the previous version.
Saving Packing Lists in XML ! 263
12
Creating and Using Web Services
CHAPTER
This chapter provides information about using AR System and web
services to connect to other applications across the internet or an
intranet. It describes how to publish AR System functionality as a web
service and how to invoke web services created by external
applications to push data to these external applications or to make the
data from these external applications available through the AR System.
!
Describing Web Services on page 266
!
Web Services and the AR System on page 267
!
Creating and Publishing a Web Service on page 268
!
Consuming a Web Service on page 289
!
Mapping to Simple and Complex Documents on page 293
!
XML Editing on page 306
!
Data Types on page 316
!
SOAP Headers and Authentication on page 318
!
Configuring with Internet Access Through a Proxy Server on page 320
!
Examples on page 322
Creating and Using Web Services ! 265
Describing Web Services
A web service provides an interface that enables messages to be sent to and
received from an application over a network (Internet or intranet), using
standard Internet technologies. It uses a combination of protocols such as
HyperText Transfer Protocol (HTTP) and Extensible Markup Language
(XML), which are platform independent, thus enabling the application to be
accessed regardless of its hardware, software platform, or programming
languages.
Simple Object Access Protocol
Simple Object Access Protocol (SOAP) is used as the primary transport
protocol for the messages shared by applications in web services. SOAP is an
XML-based packaging format for the information being transferred, and also
contains a set of rules for translating applications and platform-specific data
types into XML.
Message Styles
Web services have two styles of messaging:
!
Remote Procedure Call, or RPC-style, in which one application makes a
function call to another application, passing arguments and receiving
return values.
!
Document-style, in which applications exchange XML documents whose
syntax are defined by an XML schema, for example a Purchase Order
document.
Both these styles can be divided into literal or encoded substyles. Literal
means that the messages will be encoded according to the XML schema, and
encoded means that the messages are constructed according to SOAP
encoding rules. The resulting four possible styles and sub-style combinations
are: RPC-Literal, RPC-Encoded, Document-Literal, and
Document-Encoded.
Further variations are possible, but they are not used in the AR System. The
style you choose depends on your compatibility requirements. To
communicate with MicrosoftDotNet, use Document-Literal. For everything
else, you would typically use RPC-Encoded. For complex documents, use a
literal format since AR System does not yet support arrays and structures in
the encoded formats.
266 "Chapter 12—Creating and Using Web Services
Web Service Description Language (WSDL) File
Web Services Description Language is an XML-based language used to define
web services and how to access them. For an example of a WSDL file, see
Further information on SOAP and specifications for WSDL can be found at
the following sources:
http://www.w3.org/TR/SOAP/
http://www.w3.org/TR/wsdl
Web Services and the AR System
Web services enable AR System functionality to be available over the web
(publishing), and enable the AR System applications to access third-party
applications. For both publishing and using web services, you specify a base
form to which the information is set, or through which the information is
pushed to other forms or applications. You need to map the AR System fields
on your base form to input or output parameters of a web services operation.
A field can participate as either an input parameter, an output parameter, or
both. You can map to a simple flat document or a complex hierarchical
document involving parent and child relationships.
Preliminary Tasks
!
To create and use a web service, ensure you check the web service option
during the installation of the AR System Server.
!
You must install JRE before installing or upgrading the AR Server,
otherwise the web services will not work correctly.
!
If you install JRE after the AR Server, either reinstall the server, or add the
following lines to your ar.cfg file (default location: C:\Program Files\AR
System\):
ARF-Java-Class-Path: C:\Program Files\AR System\arapi51.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\axis.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\log4j-core.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\websvc51.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\wsdl4j.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\xercesImpl.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\xmlParserAPIs.jar;
Web Services and the AR System ! 267
!
ARF-Java-Class-Path: C:\Program Files\AR System\commons-logging.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\jaxrpc.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\tt-bytecode.jar;
ARF-Java-Class-Path: C:\Program Files\AR System\saaj.jar;
#ARF-Java-VM-Options: -Dhttp.proxySet=true -Dhttp.proxyHost=zermatt
-Dhttp.proxyPort=3129
Plugin: WebService.dll
Also if you install JRE after the AR Server, add the JRE directory to your
PATH, for example:
C:\Program Files
JavaSoft\JRE\1.3.1_03\bin\hotspot
If you install the server after installing JRE, the server installer will
automatically update your ar.cfg file and set your PATH.
!
The Web Services feature also requires JRE for AR System Administrator,
but the timing of the JRE installation does not affect this function.
!
The first time you use the web service after installation, access the Web
Service Settings page in the Configuration Tool and enter “Demo” in the
Anonymous User Name field, otherwise you will see an error message
(Error 149: A user name must be supplied...).
Creating and Publishing a Web Service
The web service is created and modified in AR System Administrator using
the Web Services Graphical User Interface. Publishing web services makes
AR System operations available over the Internet or an intranet network.
External Client
Soap
Request
Web Service Provider (Mid Tier)
XML
Processing
DLL
Soap
Request
API
Wrapper
Soap
Response
ARServer
Soap
Response
AR
Structures
XML2AR
AR2XML
AR
Structures
Figure 12-1: External Web Service Client Calling to AR System (Publishing)
Data
Access/
Modification
The Base Form
Each web service has a base form on which it operates. You specify this when
you create your web service. When you create a web service by right-clicking
on a form name in the server window, the Base Form field is automatically
filled for you. Web services that are published in AR System can be very basic,
such as creating a record in the AR System database, or more complex, such
as processing a purchase order that spans across multiple AR System forms.
For multiple AR System forms, the base form is the master form.
Operations
Each web service has a list of operations. You can name these operations
anything you like, but these operations have to be one of three types: Create,
Get or Set. When you create a web service, by default it automatically has four
named operations: OpCreate, OpGet, OpGetList, and OpSet. OpCreate is of
the type Create, OpGet and OpGetList are of the type Get, and OpSet is of the
type Set. You can rename these operations, delete some operations, or even
create new operations, but they must be one of these three types Create, Get,
or Set. You can have more than one operation of the same type, or you can
have no operations of a particular type. For more information, see Operation
Types on page 283.
Mapping
Each operation has an “input mapping” and an “output mapping.” A
mapping describes how individual elements of the incoming and outgoing
XML document are mapped to fields and forms of the AR System. These are
essentially the input and output parameters of the web service. Mappings are
edited through the mapping dialog box of AR System Administrator; for
mapping procedures, see Mapping to Simple and Complex Documents on
page 293. When you create a web service, default input and output mappings
are provided for each of the four default operations: OpCreate, OpGet,
OpGetList, and OpSet. You can change the mapped fields. You can also
change the name of the XML element that a field is mapped to, and you can
create more XML elements.
XML Schema
Each web service may be associated with an XML schema (.xsd file). Global
elements and complex types referred to in the schema can be used in
mappings associated with operations. For more information, see XML
Editing on page 306.
Creating and Publishing a Web Service ! 269
Saving Your Web Service
Once you have selected the base form, defined your operations, and created
input and output mappings for each operation, you need to save the web
service. When you save the web service in AR System Administrator tool, it
creates a Web Services Description Language (WSDL) file that describes the
web service. This file is in standard, formal XML format; it contains all the
details necessary to interact with the service, including message formats,
transport protocols, and location.
The WSDL file can be accessed with a URL using this syntax:
http://<midtierwebserver>/arsys/WSDL/<arserver>/<webservice>
Once you save your web service, there are no additional steps. Your web
service is ready to use. You can type the WSDL URL into your browser
address field to verify that your web service is ready.
Basic Web Services
To create a web service using the default settings, right-click on a form to
display the Create WebService dialog box and save the web service.
The resulting web service will have four operations, OpCreate, OpSet,
OpGetList, and OpGet. For each of these default operations, AR System
Administrator tool has already defined input and output parameters. For the
fields on your base form, the system provides an XML compliant element
name and maps it to an input and output parameter, where applicable. These
XML compliant names are used in the generation of the Web Service
Description Language (WSDL) file for the web service. An external client can
call this web service and create, modify, or get records from your form.
Creating a Basic Web Service Using the Defaults
1 Open a server window.
2 Select the appropriate server.
3 Create a form to use as your base form if you do not already have one.
4 Expand the list of server objects and select the Form object to display a list of
available forms in the pane on the right.
5 Right-click on the form that you want to use as the base form (see the
following figure).
This is the form through which your web service operations will function.
Figure 12-2: Right-click the Base Form to Create a Web Service
6 Select Create Web Service from the pop-up list. The Create Web Service
dialog box appears as shown in the following figure.
Figure 12-3: The Create Web Service Dialog Box
The default settings are as follows:
!
The Name field is automatically populated with the web service name
based on your selected form name.
!
The Base Form field is automatically populated with the name of the
selected form.
!
The Service Type is the default document-literal.
!
The XML Schema, Label and Description fields are blank.
!
The default operations are displayed in the Operations List. They are
OpCreate, OpGet, OpGetList, and OpSet.
!
A qualification is automatically created for Get and Set operations. You do
not need a qualification for the Create and GetList operations.
!
The default XML complex types, elements and input and output
mappings are automatically set for each operation.
7 Set the Permissions, Change History, and Help Text as necessary. The
permissions are the same whether the web service is visible or hidden.
Set the permissions to Public. This is very important if you are going to
publish your web service over an internet or intranet for general use.
8 Save your Web Service.
9 Click the WSDL tab to see the URL for your Web Service Description
Language (WSDL) file.
You will see a URL for your WSDL file displayed in the field.
Figure 12-4: URL Displayed in WSDL Field
10 Replace <midtier_server> with the name of the web server where the mid tier
is running. In the figure above, studio, as the currently running AR System
server name, appears in the URL; in Figure 12-5 on page 274, the mid tier
server is kats, the port number is 8080, and the AR System server name is
KATS.
11 Click the View button to view your WSDL file in the window.
Figure 12-5: A WSDL File Displayed in the WSDL Tab of the Web Service Dialog Box
To enable your clients to communicate with your web service, see Writing
Web Service Clients on page 281.
Custom Web Services
You can change some of the items to customize your web service, including
the following:
!
Rename the Web Service—The default name is the same as the base form
name.
!
Rename the operations—The default names are OpGet, OpGetList,
OpSet, and OpCreate.
!
Remove operations and add new ones—The four operations named above
are added by default.
!
Remove fields and add new ones to the mapping—Some fields are present
by default.
!
Include only some parts of special fields in your mapping—All parts are
present by default. An example would be attachment fields with multiple
parts such as attachmentName, attachmentData, and
attachmentOrigSize. You can select only those parts that you require.
!
Rename XML element names—AR System Administrator names the XML
elements the same as the field names but removes any special characters
and spaces to make the names compliant with XML naming conventions.
You can choose any XML compliant name to map to your fields. You can
also import an XML document and use the existing XML names to map
to your fields.
!
Modify the XML structure—Examples would be to group together certain
fields to make “complex-types” or “SOAP-structures,” or designate a field
as an attribute rather than a sub-element.
!
Select the message system for the web service communication—
RPC/encoded, RPC/encoded with first parameter as XML string, or
document/literal.
!
Specify an external XML schema and use global elements/complex types
in various operations.
Creating a Custom Web Service
Follow step 1 to step 6 on page 272 in Creating a Basic Web Service Using the
Defaults, and continue from step 7 on page 276 or use the New Server Object
selection box, as described in the following procedure:
1 Open a server window.
2 Select the appropriate server.
The New Server Object dialog box opens as shown in the following figure.
Figure 12-6: New Server Object Dialog Box
4 Select Web Service from the list.
The Create Web Service dialog box appears as shown in Figure 12-7 on
page 277.
5 Enter the name of the web service in the Name field.
It is helpful to make the name descriptive and indicative of the web service’s
function. The web service name should not be the same as any existing active
link guide, filter guide, packing list, or application. The default is the same
name as the base form.
6 Select the form from the Base Form list that you are going to use.
This is the form through which your web service operations will function.
7 Select a Service Type from the list, see Message Styles on page 266 for more
information.
8 Type in or browse to an external XML schema, or leave blank to use a default
XML schema in the XML Schema field. The options are:
!
If you want to use an external XML schema, the elements or complex types
contained in this file will be used for the mapping of AR System form fields
to operation parameters. See Importing an External XML Schema on
page 314 for more information on using an external file.
!
If you leave the field blank, AR System Administrator will create an XML
schema for you using default element names.
Figure 12-7: Create Web Service Dialog Box
If you selected an XML schema:
9 Click the Load button to load the XML schema.
The AR System will verify the XML schema and load it into the memory. You
may see a message informing you that your existing XML elements and
mappings will be lost, or a schema imported successfully message. Click OK.
10 Click the Options button to display the Advanced Properties dialog box as
shown in the following figure.
Figure 12-8: Advanced Properties Dialog Box
a Choose Embedded if you had entered a local file system path for your
XSD. In this case, AR System stores the entire XSD file and all other files
that the XSD file includes or imports. The WSDL also has all the XSDs
embedded in the types section. This is the default option.
b Choose Linked if you had entered a network accessible path (http or ftp)
for the XSD. In this case, AR System does not store the XSD files. Neither
does the WSDL embed the XSDs in the types section, instead it refers to
them. Some WSDL parsing tools (early versions of Microsoft.Net and
MSSOAP) do not support these kind of WSDLs.
In the case of a system generated schema, it is always embedded in the WSDL.
11 Type a label for the web service in the Label field.
Label names can be as many as 80 characters, including spaces. This is the
how the web service will be displayed in the Web Services list in the Server
Window. If there is no label, the web service name is used.
12 Enter an optional description in the Description field. Describe what the web
service does and how it can be used, so that callers of the web service can
determine if the web service has the functionality that they require.
The default operations are displayed in the Operations List. The default
operation types are Create, Set, and Get; the operation names are OpCreate,
OpSet, OpGet, and OpGetList (there are two operations of the Get type). The
same operation can be added multiple times.
13 Select an operation from the list.
Each operation is defined by its name and type of operation, and the Name
and Type fields are automatically populated.
For the Set operation:
Click the Options button to display the Set Query Options dialog box, as
shown in the following figure. You can set all the fields on the form, or a
partial or full composite option. See Line Items on page 297 for situations
where this is applicable.
Figure 12-9: Set Query Options Dialog Box
14 Customize your operations as required.
Creating a New Operation
Creating a new operation resets the mappings to the defaults.
a Select an existing operation from the list.
b Click the New button.
“Operation” will appear in the Operations List and in the Name field.
c Enter the new name in the name field.
d Click Modify.
The new operation will appear in the Operations List.
Copying an Operation
Copying an operation retains the existing mapping information.
a Select an existing operation from the list.
b Click the Copy button.
c Change the name in the name field.
d Click Modify.
The copied operation will appear in the Operations List.
Deleting an Operation
a Select the operation from the Operation List.
b Click Delete.
The operation will be deleted from the list.
Changing the Name of an Operation
a Select the operation from the Operation List.
b Type the new name in the Name field.
c Click the Modify button.
The operation with its new name will appear in the Operations List.
Enter a qualification in the Qualification bar (optional). When you select the
Set or the Get operation, the Qualification bar will be enabled. You cannot
use an attachment field as a field reference in a qualification.
!
For the Set operation, you can enter a query that will enable the web
service to find the Request ID of the fields involved if the Request ID is not
known.
!
For the Get and GetList operations, you can enter a query that will identify
the field whose value you want to pass back to the web service as the
output parameter.
14 Map your parameters.
For mapping to simple and complex documents, see Mapping to Simple and
Complex Documents on page 293.
15 Set the Permissions, Change History, and Help Text as necessary. The
permissions are the same whether the web service is visible or hidden.
Set the permissions to Public. This is very important if you are going to
publish your web service over an internet or intranet for general use.
16 Save your Web Service.
17 Click the WSDL tab to see the URL for your Web Service Description
Language (WSDL) file.
server name, appears in the URL.
For Example:
http://<midtier_server>/arsys/WSDL/studio/ws_sample
would be:
http://studio/arsys/WSDL/studio/ws_sample
19 Click the Load button to view your WSDL file in the window. See Figure 12-5
on page 274 for an example.
Writing Web Service Clients
You need to enable your client to communicate with your web service.
Popular environments for writing web service clients are Microsoft.Net and
Apache AXIS. These environments have tools that automatically generate
code to invoke a web service, given the WSDL.
!
In Microsoft.Net Visual Studio, autogenerate the invocation code by
“adding a web reference.” When prompted for a URL, enter the your
WSDL URL.
!
In AXIS, run WSDL2java from the command line with the WSDL URL as
a command line parameter. The autogenerated code will be a class which
has methods that correspond exactly to the operations that you created in
the web service.
Each method will have input and output parameters corresponding to the
mappings you created. To invoke the web service, you need to instantiate the
class and invoke a method with the correct parameters.
For more information, see the White Paper on Instructions for Creating Web
Service Clients available from the customer support web site at
http://supportweb.remedy.com
Flow for Publishing a Web Service
The flow for publishing a web service in AR System is as follows:
1 The external client sends a Simple Object Access Protocol (SOAP) request to
the mid tier.
2 The mid tier extracts the web service name and the operation name from the
SOAP request packet. It retrieves from the AR System server, the web service
object corresponding to the web service name, and searches the web service
for details about the operation, such as the operation type (Create, Get, and
Set), the query string, and the input and output mappings. Then it expands
the xpath expressions in the query string, extracts the XML document from
the SOAP request packet, and sends it to the AR System server along with the
operation type, the input and output mappings, and the expanded query
string.
3 The AR System server parses the XML document using the mapping
information and converts it into field data. The data is treated differently
according to the operation type:
!
For the Get operation types, the AR System server ignores the input fields.
!
For the Create operation type, the AR System server creates a new entry
with the input fields.
!
For the Set operation type, the AR System server searches for an entry
using the expanded query string and then modifies the data using the
input fields.
For complex documents the data is pushed into one or more forms. This
action may trigger some filters.
4 The AR server also uses the mapping information to get the data from one or
more records and generates an XML document. The data is again treated
differently according to the operation type:
!
For the Get operation type, the AR System server performs a query based
on the query string.
!
For the Create operation type, the AR System server reads the record that
was created.
!
For the Set operation type, the AR System server reads the record that was
modified.
This action may also trigger some filters.
5 The XML document is returned to the mid tier.
6 The mid tier packages the XML document as a SOAP response and returns it
to the external client.
Operation Types
Create Operation Type
External applications can use this Create operation type to submit new
entries into AR System.
When AR System receives an incoming request of type Create, it performs
the following procedures:
!
It parses the incoming XML code based on the input mapping and
generates field values.
!
It creates a new entry in the base form with these field values.
!
This new entry creation triggers the OnSubmit filters.
!
After the create action is completely successful, AR System obtains field
values from the newly created entry.
!
The action of obtaining the field values triggers the OnGetEntry filters.
!
AR System uses the output mapping to generate XML code from these
field values and sends the XML document back as a response.
The output mapping may be different from the input mapping. The input
mapping will have the incoming data, but the output mapping will have
computed data, for example the EntryId, the CreateDate, or any fields that
are set by filters.
The Create operation is similar to the action of filling in a form, submitting
it, and then searching for the same entry. All the rules for Submit also
apply—required values must be entered, system fields cannot be submitted,
and so on.
A Create operation can create only one entry in the base form. You can add
it to a web service multiple times, each time specifying a unique name for the
operation and a set of input and output mappings. Multiple Create
operations are useful if you want to make different operations available on
the same base form to accommodate different connecting applications.
Set Operation Type
External applications can use the Set operation of the web service to modify
an existing entry in the AR System.
Unlike Create, the Set operation needs a qualification to identify the entry to
modify. This qualification has to be specified in AR System Administrator at
design time. You cannot use an attachment field as a field reference in a
qualification. The qualification may be completely static, for example
‘RequestID’ = “000000000000001” which means that any incoming request
will always operate on the first entry. A more useful qualification is either
semidynamic or completely dynamic.
!
A semidynamic qualification looks like a static qualification except that it
allows XPATH expressions in its values, for example
‘RequestID’ = XPATH(“/ROOT/RequestID”)
!
A completely dynamic qualification is a single XPATH expression, for
example XPATH(“/ROOT/QueryString”).
For an explanation of XPATH expressions, see XPATH Function in
Qualifications for Web Services on page 286
When AR System receives an incoming request of the type Set, it performs
the following actions:
!
It determines if the qualification is dynamic; if so, it expands the
XPATH expressions with data from the incoming XML to make the
qualification static.
!
It searches the base form for an entry matching the qualification.
!
It parses the incoming XML code based on the input mapping,
generates field values, and modifies the matched entry.
!
The entry modification triggers the OnModify filters.
!
After the modify is completely successful, AR System obtains field
values from the recently modified entry.
!
!
The AR System then uses the output mapping to generate XML code
from these field values and sends the XML document back as a
response.
As in the Create operation, AR System returns the same entry as the one
submitted because the output mapping may be different from the input
mapping. The input mapping will have the incoming data, but the output
mapping will have computed data, for example fields that are set by filters.
The Set operation type is similar to modifying an entry in the user tool and
then clicking refresh to get back the same entry. All the rules for modify also
apply—required values cannot be nulled out, system fields cannot be
changed.
The Set operation can only modify one entry in the base form. You can add
it to a web service multiple times, each time specifying a unique name for the
operation and a set of input and output mappings.
For information on the Set operation type for complex documents, see The
Set Operation Type for Complex Documents on page 299.
Get Operation Type
External applications can use a Get operation to get details about an entry in
AR System.
Like Set, the Get operation also needs a qualification that has to be specified
in AR System Administrator. You cannot use an attachment field as a field
reference in a qualification. For the Get operation, a qualification is
automatically generated for you (this can be modified) and a particular entry
is retrieved. For the GetList operation, you need to manually enter a
qualification, or the system will retrieve all the entries. The qualification for
both operations can be static, semidynamic, or completely dynamic.
When AR System receives an incoming request of type Get, it performs the
following procedures:
!
It determines if the qualification is dynamic. If so, it expands the
XPATH expressions with data from the incoming XML to make the
qualification static.
!
It searches the base form for entries matching this qualification. Unlike
Set and Create, Get can deal with multiple entries. Also unlike Set and
Create, AR System completely ignores the input mapping, the input
XML is only used for expanding XPATH expressions. AR System gets
field values from the matched entries.
For an explanation of XPATH expressions, see XPATH Function in
Qualifications for Web Services on page 286
!
AR System then uses the output mapping to generate XML code from these
field values and sends an XML document back as a response. You do not need
input mapping for the Get operation; you can create it, but the system will
ignore it.
The default operations listed are OpGet and OpGetList. These are merely
names for the operation type Get. Use the mappings to create a Get or a
GetAll operation. Get returns one entry, and GetAll returns multiple entries.
For GetAll operations, map the form to a complex type with maxOccurs=(a
number greater than 1 or unbounded) so that the resulting records (>1) can
be passed on to the user. See The Get Operation Type for Complex Documents
on page 299 for more information.
XPATH Function in Qualifications for Web Services
When publishing web services in AR System, the Get and Set operation types
accept a qualification string. At run time, a query is made using the specified
qualification and the OpGet, OpGetList, and OpSet operations are executed
on the entries returned by the query. The format of the qualification string is
similar to that used in the advanced query bar in the user client, but there is
an additional function called XPATH, which is used only for web service
qualifications. Access the available XPATH expressions by clicking the arrow
on the right side of the Qualification bar in the Web Service dialog box and
select XPath (see the following figure).
Figure 12-11: XPath Selection for Qualification Bar
An XPATH expression is a way of identifying an XML element inside an
XML document. Its syntax is similar to a directory path syntax.
!
The XPATH function takes one argument, which must be an expression
referencing an element or an attribute in the input mapping of the
operation.
!
The element or attribute being referenced doesn’t have to be mapped to a
field; it may only exist in the XML schema and be used only for the
purpose of qualification.
!
The expression must start with /ROOT and must list all the elements in the
path including the one being referenced.
!
When referencing an attribute, use @ before the attribute name.
!
The XPATH function can be used anywhere in the qualification and a
value will be substituted based on the XML data type.
!
For strings, extra double quotes around the value are added by AR System.
!
For date-time fields, the XML date time string is converted to the number
of seconds.
!
If more than one element matches the expression, the first element is
considered.
!
An entire qualification string can be passed as one of the XML elements in
the input document to create totally dynamic queries. This is analogous to
using the EXTERNAL function.
!
If an element is missing in the input document, then it is resolved to
$NULL$.
XPATH expressions are similar to field references, for example suppose you
have this qualification:
‘RequestID’ = $RequestID$
$RequestID$ is the value of the RequestID field in the current entry, and
‘RequestID’ is the field you want to search on.
Similarly:
‘RequestID’ = XPATH(“/ROOT/RequestID”):
XPATH(“/ROOT/RequestID”) is the value of the RequestID in the current
XML document, and ‘RequestID’ is the field that you want to search on.
Here is an example of an XML document and some sample qualification
strings using XPATH expressions:
<? xml version=”1.0” ?>
<ROOT>
<Employee ID=”112”>Adam</Employee>
<Address>
<Street>1500 Salado Dr</Street>
<City>Mountain View</City>
</Address>
<HireDate>2002-01-01T00:00:00.0000000-08:00</HireDate>
<query>
<qualification>’Employee_ID’ > 100</qualification>
</query>
</ROOT>
Sample Qualification
XPATH Resolved
Qualification
Comments
‘Employee_Name’=XPATH(/R ‘Employee_Name’= Employee is of type: string.
OOT/Employee)
”Adam”
‘Employee_ID’=XPATH(/RO
OT/Employee/@ID)
‘Employee_ID’=112 ID is an attribute of type:
integer.
‘City’=XPATH(/ROOT/Add
ress/City)
‘City’=”Mountain
View”
‘HireDate’=XPATH(/ROOT/
HireDate)
‘HireDate’=1009872 HireDate is of
000
type:dateTime. It converts
to the number of seconds
since 1/1/1970.
‘State’=XPATH(/ROOT/Add
ress/State)
‘State’=$NULL$
XPATH(/ROOT/query/qualifi
cation)
‘Employee_ID’>100 Qualification is of
type:string.
City is of type: string.
State does not exist in the
input document.
For information on the XPATH specification, go to
http://www.w3.org/TR/xpath
Consuming a Web Service
WebService
Plugin-Filter
ARServer
Data
access
and
filter
process
-ing
AR
Structures
XML
Processing
DLL
XML2AR
AR
Structures
External
Web Service
Soap Request
Soap
Handler
AR2XML
Soap Response
Figure 12-12: Calling Out to an External Web Service (Consuming)
Creating the Set Fields Filter to Import an External Web Service
You use an external web service by creating a Web Service Set Fields filter
action to enter the data from the web service into your base form. You can
then view the form in an AR System client. Ensure that you do not have other
filters acting on the same form that might skew the data, or prevent the data
from the external web service from displaying.
Creating a Set Fields from Web Service Filter Action
1 Create a form to use as your base form for the external web service.
Before you create your fields to hold the data, check the WSDL file to see the
element types that you are going to map to your fields. You can only map
fields and XML elements of the same type. Also, If you hover your cursor
over the field name or XML element displayed in the mapping dialog box, the
tooltip will show the data type.
In the Server Window:
2 Select the relevant server.
4 Select Filter from the list, and click OK.
The Create Filter dialog box appears with the Basic tab selected.
5 Enter a name for your web services filter in the Name field.
6 Select or clear the Enable check box to enable or disable the filter.
Consuming a Web Service ! 289
You may want to disable it during development or when you are diagnosing
a problem.
7 Enter the execution order in the Execution Order field for the filters.
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. Bear in mind that some filter actions may be in a queue and
performed at a later time.
8 Select the Base form from the Form Name list.
This is the form to which the data will be set. You can push the data to other
forms by creating workflow.
9 Select from the Execute On category, the operation that will activate the set
fields filter.
If you select multiple options, the filter will execute when any one of the
selected operations occurs.
10 Enter a qualification statement in the Run If field if you want to refine the
selection criteria.
You can type the qualification or you can build it by using the qualification
bar and field list. When the qualification is met, the If Actions execute. When
the qualification is not met, the Else Actions execute.
12 Select Set Fields in the New Action list.
13 From the Server Name field list, select the server on which the web service
mappings will be stored as a server object.
14 From the Read Value for Field From list, select Web Service.
Figure 12-13: Create Filter Dialog Box
15 Enter the URL for the Web Service Description Language (WSDL) file for the
web service that you require.
16 Click Load.
AR System Administrator parses the WSDL file, identifies viable operations,
and lists them in the Choose Operation field.
The name of the web service is displayed automatically in the Web Service
Name field.
17 Choose the operation that you would like the web service to perform.
18 Map the input and output mapping by clicking on the appropriate icons. For
mapping procedures, see Mapping to Simple and Complex Documents on
page 293.
19 Save your Set Fields from Web Service filter action.
You can view the Web Service data by opening the base form and other forms
to which the data is pushed, in an AR System client.
Consuming a Web Service ! 291
Flow for Consuming a Web Service
The flow for using a web service in the AR System is as follows:
1 A filter process triggers a Set Fields from Web Service filter.
2 The filter uses the mapping information stored on the server to construct an
XML document from data from the base form and the child form (if any).
3 The AR System server sends the XML document to a WebService PlugIn
Filter.
4 The WebService PlugIn Filter receives the XML document and packages it
into a Simple Object Access Protocol (SOAP) request packet and calls the
External Web Service.
5 The External Web Service replies back with the SOAP response packet.
6 The WebService PlugIn Filter extracts an XML document from the SOAP
packet and returns it to the AR System server.
7 The AR System server receives the XML document and then uses the
mapping information to parse the XML document and push data into the
current record and into child forms (if any).
8 The Set Fields from Web Service filter action is completed.
Consuming a Web Service Published on the Same AR System
Server
To consume a web service that is created on the same AR System server, you
must have an AR System server license. You must also increase the number
of threads.
!
Threads in the Server—If an AR System server calls itself through a web
service, twice the number of fast/list threads are used, therefore the
minimum number of fast and list threads should be more than two. The
number of server threads should be two times the expected number of
users that will be using the web services feature, if they are consuming on
the same server. Set this in the Server Information dialog box, Server Ports
and Queues tab in AR System Administrator.
Note: It is very easy to get into a deadlock situation by running out of threads
because each web service call will consume 2 threads.
!
Threads in the Plug-in—The web service will use only one thread by
default. If you using multiple web services, either external or AR System,
configure the plug-in with multiple threads. The number of plugin server
threads for the filter api (which is used in webservices.dll) can be specified
using the Filter-API-Threads: <min Threads> <max Threads> entry in the
ar.cfg file. The number of threads should be configured according to the
load; set the minimum number of threads initially to five. If the
plugin-server is not responding in time then increase the minimum
threads.
!
Timeout—If an external web service is too slow, AR System will timeout
by default in 40 seconds. Set Filter-API-Timeout:20 to set the timeout to 20
seconds.
!
Log File—Set the Plugin-Log-Level:100 to log to a file specified in the
Server Information dialog box, Log files tab in AR System Administrator.
Mapping to Simple and Complex Documents
The procedure for mapping documents is the same for both creating and
consuming web services.
Simple Documents
With a simple XML document, the fields from one form are mapped to the
XML element names. It is a simple list of ARFieldName/XMLElementName
pairs.
Mapping to Simple Documents
In the Create Web Service or the Create Filter dialog box:
1 Click the Input Mapping or Output Mapping button according to the
mapping you want to set.
The Mapping dialog box appears together with the Object Properties dialog
box as shown in the Figure 12-14 on page 294. (For using a web service, the
Form and XML Schema panes are reversed.)
The Object Properties dialog box displays properties of a selected object. You
can also display the Object Properties dialog box by right-clicking the
element name in the XML Schema pane and choosing Properties.
Mapping to Simple and Complex Documents ! 293
Items with a solid circle are mapped, those with a hollow circle are not
mapped. You can only map items of the same data type. See Data Types on
page 316 for more information.
If you left the XML Schema field blank in the Web Service dialog box, the
System Generated option will be automatically selected.
2 Click the Generate & Map button and the AR System will generate an XML
schema for you and automatically set the input and output mappings.
Figure 12-14: Mapping and Object Properties Dialog Boxes
The Forms field arrow is for adding more forms to create parent and child
relationships for mapping to complex XML Schemas. See Complex
Hierarchical Documents on page 295.
The base form name and fields are displayed in the Forms pane, and the XML
element names are displayed in the XML Schema pane.
3 If you opted for a system generated XML schema, your base form will be
mapped to the Root element in your XML Schema, and the fields in your
form will automatically be mapped to element names in the XML document.
4 Make any changes to the mapping, or the form, fields and elements in your
XML schema.
Removing an existing mapping:
a Select the field in the Forms and Fields pane or an element in the XML
Schema pane.
b Click the Unmap button.
Mapping a Field to an XML Element Name:
a Select the unmapped field in the Form and Fields pane.
b Select an available element name in the XML Schema pane.
c Click the Map button.
To add and remove fields, see Adding or Removing an Existing Field from the
Form List on page 312 and to modify the XML schema, see Adding a New
Element or Attribute on page 307 and Cutting, Copying or Pasting an Element
or Attribute on page 307.
5 Click OK to close the Mapping dialog box.
6 Save your web service.
Complex Hierarchical Documents
For complex hierarchical documents, the XML schema maps to multiple
interrelated forms. In the following example, a purchase order XML is
mapped to two forms, PurchaseOrder and LineItem. The data can be
represented by the following figure:
Request ID
PurchaseOrder
Description Date
007
XYZ Corp
2/12/02
012
ABC, Inc.
3/01/02
Request ID
LineItem
Ln ID Description PO ID
0015
0016
0017
1
2
3
Memory
CPU
HardDisk
007
007
007
0020
0021
1
2
Scanner
Printer
012
012
The data consists of two purchase orders, one for XYZ Corporation with
three line items: Memory, CPU, and HardDisk, and one for ABC, Inc. with
two line items: Scanner and Printer. The PurchaseOrder and LineItem are
related through the ID fields:
!
The PurchaseOrder form’s Request ID. This is the primary key in the
parent form and it is unique. This is the key that establishes the
relationship with the LineItem form’s foreign key.
!
LineItem form’s POID. This is the foreign key in the child form; it
establishes the relationship with the PurchaseOrder form’s primary key.
!
LineItem form’s Request ID. This is the primary key in the child form and
is unique.
!
LineItem form’s Line ID. This is unique only within the subset of requests
that reference the same PurchaseOrder. The LineID together with the
POID form a “unique key.”
The XML input document in the example could be as follows:
<PurchaseOrder>
<Customer>XYZ Corp</Customer>
<Date>2/12/02</Date>
<Items>
<LineItem> <Id>1</Id> <Description>Memory</Description> </LineItem>
<LineItem> <Id>2</Id> <Description>CPU</Description> </LineItem>
<LineItem> <Id>3</Id> <Description>HardDisk</Description>
</LineItem>
</Items>
</PurchaseOrder>
The XML document does not include Request IDs. Request IDs have no
meaning outside the AR System unless they are used as the primary key
identifier for the document. For example, if the purchase order (PO)
document uses the Request ID field as the PO Number, then that is used
externally as well. In that case, the request ID field will probably be renamed
as the PO Number field. The server automatically creates Request IDs for the
parent and child forms, and assigns foreign keys to the child form as the
identifier between the child and parent.
The only IDs present in the XML document are the LineIDs of the child form.
These LineIDs can be numbers, or strings, such as the description. The
LineIDs are only used in the modify operation: the server compares the
existing complex document with the new document and determines which
child items to modify, insert, and delete.
Nillable Attributes
To render a null field, create an empty element with xsi:nil=true as an
attribute. This is preferable to omitting the element in the request document,
or creating an empty element with nillable attribute set to false. For more
information on nillable attributes, see Object Properties on page 307.
Line Items
For a complex document, such as a purchase order that has, for instance
three line items, where you submit an XML document containing two line
items for a Purchase Order already existing in the system, the server
compares the LineIDs of the existing three line items with the Line IDs of the
two new line items. The following rules apply:
!
If there are matching LineIDs, the server updates the line item in the
database with the contents of the XML elements inside the corresponding
line item in the input document. Fields for which the XML elements are
missing are left untouched.
!
If a new LineID does not exist in the database, the server creates a new
record in the line item form.
!
If there is a missing LineID, that is, a line item exists in the server but not
in the input request, the server either deletes the line item from the server
or ignores it, depending on the option that you choose in the AR System
Administrator when you are creating your Set operation type.
!
If you select Full from the list in the Composite Option field in the Set
Query Options dialog box (see Figure 12-9 on page 279), the server will
delete missing line items.
!
If you select Partial from the list in the Composite Option field in the
Set Query Options dialog box (see Figure 12-9 on page 279), the server
will ignore missing line items.
As a consequence of these characteristics, a modify operation for a complex
document can result in create and delete actions.
You must ensure that each LineID is unique within the scope of one
document. The server will not be able to distinguish between duplicate
LineIDs when performing a modify action and if this happens, results may
not be as expected.
Choice Element
The choice element in XML schema gives the flexibility of listing a set of
elements. The XML instance document using this schema can specify only
one of the elements mentioned for choice. In the AR System web services,
when you are mapping input from an XML document it is easy to ascertain
which element is used for choice. But when you are generating an output
XML document from AR System forms, it is not obvious that you need to
select only one of the choice elements. To resolve this, a choice node in the
XML schema can be mapped to a character field. When an input XML
document is received, the name of the element given for choice is stored in
this character field. The value in this character field will be used in generating
the output XML document for choice.
The following bullets give further details about the choice elements in AR
System:
!
Direct or indirect children of choice cannot be mapped to another form.
!
Choice can have only elements. It cannot have immediate choice,
sequence, group and so on.
!
A choice can appear in a sequence or in a complex type.
!
Recursion in choice is not allowed.
!
“minOccurs” attribute of choice can be either 0 or 1. Any number greater
than 1 or unbounded is not supported.
!
“maxOccurs” attribute of choice must be 1. Any number greater than 1 or
unbounded is not supported.
!
Choice does not reset other items during a Set or Create operation. It only
sets the item that has been sent.
For further information, see the white paper on Limitations available from
the Customer web site at: http://supportweb.remedy.com
The Set Operation Type for Complex Documents
The Set (or Modify) operation for complex documents is more complicated
than that for the simple document. In a simple document, your base form
may have ten fields, all mapped to XML elements. If your modify request
XML is returned with all ten XML elements, the server will modify each of
the ten fields with data from the ten XML elements. However, if your modify
request XML is returned with fewer than ten elements and you have specified
MinOccurs=0 in the Object Properties dialog box for the XML elements, the
server will only modify the fields that are present in the input request. If your
modify request XML is returned with fewer than 10 elements, and you have
set MinOccurs to equal other than 0, you will receive an error message.
The Get Operation Type for Complex Documents
For GetAll (GetList) operations, map the form to a complex type with
maxOccurs=(a number greater than 1 or unbounded) so that the resulting
records (>1) can be passed on to the user. Instead of mapping the form to the
ROOT element, which cannot have maxOccurs=unbounded, map to
another element below ROOT which has maxOccurs=unbounded. All the
fields on the form for a GetAll operation should be mapped to the children
of this element rather than being mapped to children of ROOT. The default
GetList operation already has this element called “getListValues,” however, if
you are creating custom mappings, ensure that this element exists.
Filter Flow for Complex Documents
When a complex document, such as the PurchaseOrder on page 295 is
received by the AR Server, the AR Server updates the LineItem form by
generating Push Field actions on the Purchase Order form for every line item
in the Purchase Order document.
!
For publishing: the Push Fields actions relating to the web service are
executed before other Push Fields actions on the Purchase Order form are
executed.
!
For consuming: the Push Fields actions generated during the
consumption of a web service are executed before other Push Fields
actions on the Purchase Order form.
!
For a form with both publishing and consuming web services: the filter
flow is as follows:
Publishing Push Fields actions > Consuming Push Fields actions > Other
Push Fields actions.
Mapping to Complex Documents
To create the mapping of a complex document, you need to have created
your forms and created a complex XML Schema. See Advanced XML Editing
on page 313 for more information. Choose the parent form as the base form
of the web service and additional forms are used as child forms. A child form
should not be used with more than one parent form. Also, to publish a web
service, enter an XML Schema in the Web Services dialog box, and click Load
In the Create Web Service or the Create Filter dialog box:
1 Click the Input Mapping, or Output Mapping button according to the
mapping you want to set.
The Mapping dialog box appears.
2 Select an external XML schema or a system generated one.
a If you want the AR System to automatically generate an XML schema,
click System Generated and then Generate and Map.
b If you have selected an external XML schema, select the XML Schema
option button.
c Select Support XSIType, if necessary. If this option is checked, the system
specifies xsiType for all XML data while creating XML documents.
d Click the Choose button.
The Choose start element dialog box is displayed showing complex types
and elements, as shown in the following figure:
Figure 12-15: Choose start element Dialog Box
e Choose your start element, or start complex type. See Importing an
External XML Schema on page 314 for more information.
Your XML elements and complex types will be displayed in the XML Schema
pane and your parent form will be displayed in the Forms pane as shown in
the following figure. (For using a web service, the Form and XML Schema
panes are reversed.)
Figure 12-16: The Mapping Dialog Box
The Object Properties dialog box displays properties of a selected object. You
can also display the Object Properties dialog box by right clicking the element
name in the XML Schema pane and choosing Properties.
Items with a solid circle are mapped, those with a hollow circle are not
mapped.
3 Add additional forms to the list using the Forms menu. These will be child
forms.
All the selected forms and their fields will be listed in the Forms pane.
Figure 12-17: Mapping Dialog Box Showing Mapping of Forms, Fields and Elements
4 Select the parent form name from the Forms pane.
5 Select the ROOT element in XML Schema pane to map the parent form. The
parent form is typically mapped to the ROOT element
The Define form mapping dialog box appears as shown in the following
figure. Only character fields are listed that have been specified as Unique in
the Indexes tab of the Form Properties dialog box.
Figure 12-18: Define Form Mapping Dialog Box
6 Select the field from the list to use as the primary key.
This is the field that uniquely identifies the entries in the specified form. It is
typically the Request ID field.
The foreign key field is disabled for the parent form.
7 Click OK to close the Define form mapping dialog box.
8 Map any other the fields in the parent form to elements in the XML schema.
Note: You must map to the same data types. If you hover the cursor over the
XML element name or field name, the tooltip shows the data type. See
Data Types on page 316 for more information.
9 Map a child form in your forms list to elements in the XML schema list.
The Define form mapping:Establishing master detail relation dialog box
appears.
Figure 12-19: Define Form Mapping:Establishing master detail relation
10 Select the Field to distinguish this detail item from others. This is the value
that uniquely identifies each of the detail items in the child form of any given
parent entry.
11 Select the Field to link the parent form with the current form (Foreign Key).
In our purchase example, it could be the POID.
The combination of distinguishing key and foreign key should uniquely
identify an entry in a child form. AR System Administrator does not enforce
this, but AR System server will return an error if it detects non-compliance.
A field specified as foreign key should not be used in any field mapping since
this field is used by system to store the foreign key. If it is mapped, that
mapped XML element's value is usually overridden by foreign key value but
this may not happen in all cases.
12 Map any other fields in the child form to XML elements.
13 Repeat step 9 to step 12 to map any other required child forms to XML
elements.
Note: The immediate children of all or choice cannot be mapped to another
form.
To map choice nodes, first map the choice node in the XML schema to the
choice field in a form before mapping the choices. In Figure 12-18 on
page 302, for example, you would map PhoneNumber/EmailID field to the
choiceNode element, then map the Phone Number field to the
PhoneNumber element and the Email ID field to the EmailID element.
For further information, see the white paper on Limitations available from
the Customer web site at: http://supportweb.remedy.com
Using Join Forms in Web Services
You can use join forms in web services but only for parent forms, child forms
cannot be join forms. For more information on join forms, see the
Primary Keys
Join forms can be used for publishing or consuming in the same way as
regular forms except for certain considerations when choosing a primary key
in the Define form mapping dialog box. When you map the parent form, the
primary key must be unique to the join form. The base forms which comprise
the join form can each have a unique key. The Request ID of the join form is
a concatenation of the Request IDs of the join base forms.
Since the primary key must be unique to the join form, this provides the
following possibilities.
!
For a Create operation.
When you publish a web service using a join form, a Create operation is
not automatically generated, you need to make the Create operation
yourself.
If the join form is an inner join, the Primary key may be a Unique Index
from any of the base forms that comprise the join form.
If the join form is an outer join, the Primary key may be a Unique Index
only from the primary base form.
The primary key cannot be the Request ID field.
!
For Set operation.
If the join form is an inner join, the Primary key may be one of the
following:
!
the Request ID of the join form
!
the Request ID of any of the base forms
!
a Unique Index from any of the base forms.
If the join form is an outer join, the Primary key may be one of the
following:
!
the Request ID of the join form
!
the Request ID of the primary base form
!
a Unique Index of a field from the primary base form.
Output Mapping
In a Create operation, if the web service base form is a join form, the output
mapping is ignored and neither a document nor a Request ID returned.
Example
In the following example, PO - People is an inner join form between the PO
form and the People form.
The Unique key in the PO form is POID, the Unique key in the People form
is Name, and the join criteria between the two forms are Name (of PO form)=
Name (of People form)
Since the Unique key POID will also be unique in the join form, we choose it
to be the Primary key.
People Form
PO Form
POID
Company Name
PO Date
Creator Name
Join Criteria: Creator Name
Creator Name
Creator Phone
POID
Company Name
PO Date
Creator Name
Creator Phone
PO-People Form
Line ID
Item Description
Line Item Form
1 Underlined text indicates the Primary Key 2 Text in bold indicates Unique keys
Figure 12-20: Join Form in Web Services
XML Editing
You can perform simple editing tasks with the AR System Administrator or,
for more complex documents, you can create and edit an XML schema
outside the AR System and import it. The following sections provide
information about simple and complex XML editing.
Simple XML Editing
AR System Administrator allows you to change the format of the XML code
so that is compatible with your web service. The following changes are
possible:
!
You can add, delete, or rename the XML elements.
!
You can create XML elements to enable grouping of existing XML
elements. This grouping is purely cosmetic.
!
You can use attributes instead of elements.
!
You can set nillable, MinOccurs, and MaxOccurs attributes of elements.
Adding a New Element or Attribute
1 Right-click an element in the XML Schema pane to display a list of actions.
2 Choose New > Element or New > Attribute.
The new element or attribute will appear one level below the selected item.
3 Enter the name of your new element or attribute.
Cutting, Copying or Pasting an Element or Attribute
1 Right-click an element in the XML Schema pane to display a list of actions.
2 Select the required action.
Paste to enter the new item one level below the item selected.
Object Properties
The properties of an object indicate the information that the object provides.
You can set various property values for the XML Schema objects using the
Object Properties dialog box as shown in the following figure.
Figure 12-21: Object Properties Dialog Box
To edit a property value, select XML Element Info in the Property Type field,
click the item in the value column corresponding to the property you want
to edit and either select or type the value.
Element: If the value for Element is set to “True,” the object is an element. If
the value is set to “False” the object is an attribute. ROOT is an element and
cannot be edited.
XML Editing ! 307
XmlType: Any leaf node (element or attribute) can be identified as xmlType.
This allows the data to be treated as XML string data and AR System does not
treat it like a regular string (that is, they are not encoded or decoded).
MinOccurs: This indicates number of instances of the element. By default it
is 1. If it is zero, the element may or may not be present.
MaxOccurs: This indicates maximum number of instances of the element.
By default it is 1; unbounded indicates that the element may be repeated any
number of times. For example, a purchase order document may contain any
number of line items.
DefaultValue: This is the default value of an element unless it is overridden
by the value in the actual document (incoming or outgoing).
Nillable: Any leaf node (elements only) can be made nillable. Setting the
nillable attribute to true or false can only be done in the mapping dialog
boxes. The document is interpreted according to the following rules:
Handling null, empty and missing values
There are many subtle rules for handling null, empty and missing values.
!
Elements and Attributes mapped to fields
The rules can be divided into four groups.
!
Incoming XML elements
!
Incoming XML attributes
!
Outgoing XML elements
!
Outgoing XML attributes
AR System has two sources for incoming XML: as the request for an AR
System published web service, or as a response from an external web service
that AR System is consuming. Similarly there are two sources for outgoing
XML: as the response from an AR published web service, or the request to an
external web service that AR is consuming.
In these tables it is assumed that “name” is an XML element or attribute
which is missing, empty or nulled, and is mapped to an AR System field called
“Name.” The column headers are the design time properties, for example,
name is defined with minOccurs=0 and nillable=false. The row headers are
run time representations, for example, in the incoming XML packet “name”
appears as <name></name>. The table specifies how AR System sets the
XML element or attribute to or from the AR System field.
minOccurs=0
and
nillable=false
minOccurs=1
and
nillable=false
minOccurs=1
and
nillable=true
Missing <name>
Name is not
Name is not
This is invalid
modified or set to modified or set to XML.2
AR default.1
AR default.1
This is invalid
XML.2
<name></name>
or
<name/>
Name=$NULL$
or xsd default 3
<name xsi:nil=”true> This is invalid
</name>
XML. 5
or
<name xsi:nil=”true”/>
minOccurs=0
and
nillable=true
Name=$NULL$
or xsd default 3
Name=$NULL$
or xsd default 3
Name=$NULL$
or xsd default 3
Name=$NULL$ 4
This is invalid
XML. 5
Name=$NULL$ 4
1
When an XML element is missing, AR System treats it the same way as a
missing field, therefore, in a create operation, the field that the XML element is mapped to assumes the AR System default value. (Or NULL if there
is no default.) In a set operation and in consumption the field remains unchanged.
2
When an XML element is missing, in spite of minOccurs being 1, it is invalid XML. The client should not send such an XML packet. But if it does,
AR System displays an error.
3
When the XML element has empty content, AR System first tries to use the
xsd default if it exists. (There are two different defaults: the AR System default value and the xsd default value. For empty contents AR System always
uses the xsd default, not the AR System default.) Otherwise, it sets the field
to NULL.
4
When the XML element has xsi:nil=true, AR System sets the field to
NULL, and disregards the defaults.
XML Editing ! 309
5
When the XML element has xsi:nil=true, but is not defined with
nillable=true, it is invalid XML, and clients should not send such an XML
packet. Also, AR System sets this field to NULL disregarding the defaults.
Incoming XML attributes
use=optional
use=required
Missing <name> Name is set to xsd default This is invalid XML.2
or not modified or set to
AR default.1
name= “”
Name=$NULL3
Name=$NULL3
1
If an attribute is defined with use=optional and the attribute is missing
from the XML, AR System tries to use the xsd default. If the xsd default does
not exist, it treats the attribute like a missing field, therefore, in a create operation the field to which this attribute is mapped assumes the AR System
default value. (Or NULL if there is no default.) In a set operation and in
consumption the field remains unchanged.
2If an attribute is defined with use=required, it should not be missing,
otherwise the XML is invalid and clients should not send such an XML
packet. AR System will display an error.
3If an attribute has an empty value, AR System sets the mapped field to
NULL and disregards the defaults.
minOccurs=0
and
nillable=false
minOccurs=0
and
nillable=true
minOccurs=1
and
nillable=false
minOccurs=1
and
nillable=true
Name is $NULL$
Missing name 2
<name
<name/>3
1
xsi:nil=“true”/>
<name
xsi:nil=“true”/>1
Name is “”
<name/>3
<name/> 4
<name/> 4
<name/> 4
<name>
is not mapped
Missing name5
Missing name5
This is invalid
XML.6
This is invalid
XML.6
1If a field is null, AR System generates the XML as xsi:nil=true. However it
can do so only if nillable=true.
2
If nillable is false, AR System doesn’t generate the element at all for null
fields. However it can do so only if minOccurs=0.
IIf nillable is false and minOccurs=1, AR System generates an element with
empty content.
4
If a field is of character type and it contains an empty string (this is extremely unusual, it can be done only through the driver program), AR System generates an element with empty content.
5
If an XML element is not mapped to a field, AR System does not generate
an element for that.
6
If an XML element is not mapped to a field, but it has minOccurs=1, AR
System does not generate an element for that, which means that the XML
generated by AR System is invalid.
Outgoing XML attributes
use=optional
use=required
Name is $NULL$
name=""1
name=""1
Name is ""
name=""2
name=""2
<name>
is not mapped
Missing name3
Invalid XML 4
1
If a field is null, AR System generates an attribute with empty content.
2If a field is a character type and it contains an empty string (this is extreme-
ly unusual, it can be done only through the driver program), AR System
generates an attribute with empty content
3
If an XML attribute is not mapped to a field, AR System does not generate
an attribute for it.
4If an XML attribute is not mapped to a field, but has use=required, AR
System does not generate an attribute for it, therefore the XML generated
by AR System is invalid.
!
Elements mapped to forms
While elements mapped to fields can only have maxOccurs=1, elements
mapped to forms can have maxOccurs>1. (Actually elements mapped to
fields can have maxOccurs>1, but at run time at most one element should
appear in the incoming XML.)
XML Editing ! 311
For incoming XML, the base form can only be mapped to an element with
maxOccurs=1. (It is acceptable if maxOccurs>1 at design time, but at run
time there is at most one element.)
The child forms can be mapped to elements with maxOccurs>1. If the
number of XML elements does not fall in the range set by minOccurs and
maxOccurs, it is invalid XML and the client should not send a document
containing such XML. However AR System ignores the minOccurs,
maxOccurs constraints while parsing this XML.
For outgoing XML the base form can be mapped to an element with
maxOccurs>1 in case of publishing and an operation of type get. This implies
that multiple entries in the base form are to be retrieved. If the number of
entries in the base form is less than the minOccurs, AR System returns an
error. If the number of entries is more than the maxOccurs, AR System
returns only till the maxOccurs amount.
Child forms can be mapped to elements with maxOccurs>1. If the number of
matching entries in the child form does not fall in the range set by minOccurs
and maxOccurs, AR System returns an error.
Flat Mapping
The typical procedure is to create the XML elements and then map them to
the fields. However, if you are creating a flat mapping, you can combine these
two steps into one. Remove the fields that you do not want to map and then
click on the Generate Schema button on the Mapping dialog box. This will
create XML elements that are automatically mapped.
Removing an Existing Field from the Mapping List
1 Right-click on the field name.
2 Select Remove Field from the drop-down list.
Adding or Removing an Existing Field from the Form List
1 Right-click on the form name.
2 Select Add Fields or Remove Fields from the drop-down list.
3 Select the fields to remove from the Remove Fields list, or enter the name of
the field if you are adding a field.
Even if you have removed a field from the list and generated the schema, the
field will still be listed the next time you open the web service because it still
exists on the form. The field will display a red X to the left to indicate that it
is not mapped. However, if you delete an element or attribute from the XML
schema list, it is deleted from the XML schema and will not reappear until
you create a new entry.
XML editing is allowed only while you are publishing a web service from the
AR System. When you are consuming an external web service, the XML
format is decided by the external web service and you must conform to it. AR
System Administrator disables all editing features in that case. You can only
choose which fields you want to map to which XML elements.
XML documents may specify the data type within the document itself instead
of in the XML schema. If you want the output document to contain xsiType
information so that the consumers of the web service can process the
document correctly, check the Support xsiType option in the Mapping
dialog box. In this case, the system generates xsiType information.
Advanced XML Editing
The Mapping dialog box allows only simple XML editing. For complex
editing, you need to use an advanced XML schema editing tool, such as
XMLSpy. XML editing tools are not included with AR System. If you have a
thorough understanding of XML schemas, you can write them using a simple
text editor.
For more information, an online tutorial on XML schemas written by Roger
Costello of Mitre Corporation is available from:
http://www.xfront.com/index.html#schema.
Once you have designed an XML schema, you can import it into the AR
System Administrator. However once you import it, all the XML editing
features in the AR System Administrator are disabled. Consequently, you can
either edit the XML completely inside AR System Administrator, or
completely externally.
If you are using an old XML schema editor, the namespace for the XML
schema may be 2000 or 1999; we only support namespaces of 2001, that is,
with the declaration http://www.w3.org/2001/XMLSchema. If you use an
older version of an XSD file, your mappings may not be as expected.
XML Editing ! 313
Importing an External XML Schema
Only one external XML schema can be used for all the mappings of one web
service. However, this XML schema can include or import other XML
schemas, so if you want to use multiple XML schemas, create a new XML
schema that includes or imports all of the schemas you want to use.
In the Web Service dialog box:
1 Specify your XML Schema (XSD file) in the XML Schema field
If your schema definition is spread over multiple XSD files interlinked
together using import or include, you must type the URL of the topmost XSD
file, that is, the one which is not included or imported by others.
You can also enter a file system path to your XSD file, but the URL to the XSD
file will be referenced in your generated WSDL file, so your path must be
accessible over the network. You should make a web server directory to hold
your XSD files, and enter the http path to this directory in the Web Services
dialog box.
2 Click the Load button.
3 Click OK to accept the loss of your existing mappings, or you may see a
confirmation message.
4 Click the Options button to display the Advanced Properties dialog box as
Figure 12-22: Advanced Properties Dialog Box
a Choose Embedded if you had entered a local file system path for your
XSD. In this case, AR System loads the specified XML schema and all
dependent XML schemas. It stores the entire XSD file and all other files
that the XSD file includes or imports. The WSDL also has all the XSDs
embedded in the types section. This is the default option.
b You can choose Linked if you entered a network accessible path (http or
ftp) for the XSD. In this case, AR System does not store the XSD files, but
stores a reference to the specified schema in the web service object as well
as in the WSDL file. Some WSDL parsing tools (early versions of
Microsoft.Net and MSSOAP) do not support these kind of WSDLs.
In the case of a system-generated schema, it is always embedded in the
WSDL.
If your schema definition is spread over multiple XSD files interlinked
together using import or include, you must type the URL of the topmost XSD
file, that is, the one which is not included or imported by anyone else.
In the Input Mapping dialog box:
5 Select XML Schema.
6 Click Choose.
7 Select a start element.
The Choose start element dialog box appears. Separate mappings can be
based on separate global elements, but all of them must come from the same
XML schema. AR System Administrator displays a list of global elements and
global complex types either present directly in your XSD file, or those
included or imported into it.
Figure 12-23: Choose start element Dialog Box
If you choose an element, the element and all its successors will be added as
a child of the ROOT element, whereas, if you choose a complexType, the
contents of the complexType will be added as children of the ROOT.
If you specify and load a different schema, AR System verifies that global
elements or complex types referred to in the current mappings are
compatible with the new schema and informs you of incompatible types. If
you agree to update the existing mappings, AR System will update them for
you. If there are no overlapping global or complex types, AR System will
preserve the content of the original mapping.
XML Editing ! 315
AR System Administrator does not support all features of XML schemas, and
when using a web service there are restrictions that apply to the external
WSDL file. See the AR System 5.1 Release Notes for more information on
limitations.
Data Types
When mapping an XML element to an AR System field, AR System
Administrator only allows compatible data types. This is applicable both for
using and publishing.
Table 12-1: Compatible Data Types (Sheet 1 of 2)
AR System Data Types
XML Schema Data types
CHAR
string, duration, anyURI,
QName, NOTATION,
normalizedString, token,
language, NMTOKEN, Name,
NCName, ID, IDREF, ENTITY,
integer, nonPositiveInteger,
negitiveInteger,
nonNegativeInteger,
positiveInteger
ENUM
string
INTEGER
int, boolean, short, byte,
unsignedInt, unsignedShort,
unsignedByte
REAL
double, float
DIARY
string
DATE/TIME
dateTime
DECIMAL
decimal, long, unsignedLong
DATE
date, gYearMonth, gYear,
gMonthDay, gDay, gMonth
Defaults:
YEAR - 1000 (leap year), month
- 01,
day - 01
TIME
time
CURRENCYcurrencyValue
decimal
Table 12-1: Compatible Data Types (Sheet 2 of 2)
AR System Data Types
XML Schema Data types
CURRENCYcurrencyCode
string
CURRENCYcurrencyConversionDate
dateTime
STATUS HISTORY
string
ATTACHMENTName
string
ATTACHMENTData
base64Binary
ATTACHMENTOrigSize
int
Note: We do not support list or union data types. The list data types IDREFS,
ENTITIES and NMTOKENS are converted to strings by the AR
System.
The following complex AR System fields are treated as exceptions:
!
When you are retrieving the diary field from the AR System, the diary field
is treated as a long character field containing all the historical diary entries
separated by a special separator character. When you are sending a diary
field to AR System, you only send the current entry.
!
Status History field is treated similarly to a diary field, but you cannot send
a status history to the AR System.
!
A currency field is treated as a collection of four parts, and each part needs
to be mapped separately.
!
An attachment field is treated as a collection of three parts.
Figure 12-24: Form and XML Schema Panes in Mapping Dialog Box
Data Types ! 317
SOAP Headers and Authentication
When you publish a web service, AR System Administrator automatically
includes a SOAP header with each operation. The web service client that calls
your web service may provide a SOAP header along with the request. The
AuthenticationInfo consists of userName, password, authentication, locale
and timeZone elements. This timeZone element is an optional element,
currently, this information is not used any where. This is reserved for future
use. The SOAP header should look like this:
<AuthenticationInfo>
<userName>Joe</userName>
<password>ILoveDogs</password>
<authentication>ARSystem</authentication>
<locale>en_US</locale>
<timeZone> </timeZone>
</AuthenticationInfo>
It is through the SOAP headers that the web service client can specify which
user is authorized to perform the web service operations. You should not
send this SOAP header unless you send it over https. If the authentication
header is not specified, the user name is picked up from the AR System
Configuration Tool.
Figure 12-25: AR System Configuration Tool Web Service Settings
Note: The user must have a blank password.
You can use the name Demo for development purposes, but create another
User Name for production, such as a guest user with a blank password.
SOAP Headers and Authentication ! 319
When you use an external web service that requires a SOAP header, AR
System Administrator will automatically make an element called
SOAPHeader under the ROOT element. You can map elements inside the
SOAPHeader just as you would regular elements. The external web service
may be using the SOAP header for some other reasons not related to
authentication, for example, license keys.
If you are consuming an AR System web service, AR System Administrator
will create the SOAPHeader element and it will also automatically map the
user name and password to the current user name and password. It does so
by setting the arUserId=true and arPassword=true attributes. If you want to
pass the current user name and password to an external web service, you can
do so by setting these attributes yourself. If you do not want to send the
current user name and password to an AR Web service, you must set these
attributes to false.
Configuring with Internet Access Through a Proxy
Server
This section explains how to configure AR System Administrator and
AR System Server with Internet access through a proxy server.
Accessing Proxy Configuration Information
If your network administrator has already configured your browser
(Netscape or Internet Explorer) with proxy settings, you can view the values
in the browser’s configuration settings and insert the values in the ar.cfg file.
AR System will not automatically retrieve the browser configurations. For
Internet Explorer go to:
Tools > InternetOptions>Connections>LanSettings>ProxyServer
Configuring a Plug-in
When using a plug-in, add ARF-Java-VM-Options to your ar.cfg file— it is
case sensitive. (The default location is: C:\Program Files\AR
System\Conf\ar.cfg.)
Add as follows:
ARF-Java-VM-Options : -Dhttp.proxySet=true -Dhttp.proxyHost=<host_name>
-Dhttp.proxyPort=<port_number>
Configuring AR System Administrator
For AR System Administrator, add the proxy settings to the Registry at:
SOFTWARE\\Remedy\\AR System Administrator\\5.1\\JVMOptions
Enter as the following text:
-Dhttp.proxySet=true -Dhttp.proxyHost=<host_name>
-Dhttp.proxyPort=<port_number>
Other Protocols
https:
-Dhttps.proxySet=true -Dhttps.proxyHost=<host_name>
-Dhttps.proxyPort=<port_number>
socks:
-Dsocks.proxyHost=<host_name> -Dsocks.proxyPort=<port_number>
socks with Authentication is not supported.
If you have some internal hosts that should not use the proxy, set it as follows:
-Dhttp.nonProxyHosts="*.foo.com"
More Information
For more details about these options, see
http://java.sun.com/j2se/1.4/docs/guide/net/properties.html
Configuring with Internet Access Through a Proxy Server ! 321
Examples
The following examples provide instructions on how to create a web service
using a simple document, how to consume a simple web service, how to
create a web service using a complex document, and how to consume the web
service you created.
Example 1: Publishing a Simple Flat Document
In this example you will publish a web service that has the following default
operations for an employee record: OpCreate, OpSet, OpGet, and OpGetAll.
1 Create a form that displays your employee data. This will be the Base Form
used in creating your web service. The following figure shows a sample form.
They are all character fields.
Figure 12-26: Sample Form for Employee Record
2 Right-click on the form name (WSEmployee) in the Server Window as
Click to create the
web service using
WSEmployee as
the Base Form.
Figure 12-27: Server Window Showing Web Service Selection
Examples ! 323
The Create Web Service dialog box appears with the default settings as shown
in the following figure.
Figure 12-28: Create Web Service Dialog Box for Employee Web Service
AR System Administrator automatically populates the Base Form field with
your WSEmployee form, the default service type is document literal, and the
default web service name is the same as your base form name: WSEmployee.
The label and description fields are optional.
The default operations are automatically displayed in the Operations List.
To view the mapping:
3 Select an operation from the Operations list.
The Name field will be automatically populated with the operation name,
and the Type field will be automatically populated with the type of operation
to be performed.
The fields on your WSEmployee form are mapped to XML compliant
element names in an XML schema. Click the Input Mapping button in the
Create Web Service dialog box to view these mappings. You do not need to
modify these mappings for this example.
Figure 12-29: Mapping dialog box for Employee Web Service
A solid circle indicates that the field or XML element is mapped.
The Object Properties box refers to the XML properties of the XML elements.
4 Close the mapping dialog box.
5 Choose File > Save Web Service.
6 Click the WSDL tab on your Web Service dialog box. (See Figure 12-28 on
page 324.)
Examples ! 325
is running. In the example following, studio, as the currently running AR
System server name, appears in the URL.
http://<midtier_server>/arsys/WSDL/studio/WSEmployee
In this example:
http://remedy.studio.com/arsys/WSDL/studio/WSEmployee
9 Enter your name and password at the prompt, if necessary, and click Login.
Figure 12-30: WSDL Tab on Web Service Dialog Box for Employee Web Service
10 Set the permissions to Public.
This is important if you are going to publish your web service over an
internet or intranet for general use.
Administrators with the appropriate SOAP protocol can now access this
WSDL file with any browser.
Example 2: Consuming a Simple Flat Document
In this example you will access an external web service and, with the use of
the Set Fields to Web Service filter, push data into an AR System form. The
external web service takes a zip code as input and outputs the time of day for
that zip code.
In AR System Administrator:
1 Create a form; the one in our example is called WSZipToTime.
2 Add two character fields, one (called Zip Code in the example) in which you
will enter the zip code and one (called Time of ZipCode in our example) into
which the time for that zip code will be pushed when information is received
from the external web service.
Figure 12-31: Form for ZipToTime Web Service
Examples ! 327
4 Click Filter and OK to display the Create Filter dialog box, Basic tab.
5 Enter a Name for the filter, such as WSZipToTime.
6 Check the form WSZipToTime to use as the base form.
7 Check the Execute On Modify option button.
Figure 12-32: Basic Tab of WSZipToTime Filter
8 Click the If Action tab.
9 Select Set Fields from the New Action field.
10 Enter the name of your server on which the Web Service filter plugin is
installed.
11 Select Web Service in the Read Value for Field From field.
12 Type the path to the WSDL file of your external web service in the Choose
WSDL field:
http://www.alethea.net/webservices/LocalTime.asmx?WSDL
13 Click Load.
14 The name of the web service (LocalTime) is displayed on the dialog box
under the Web Service heading.
The available operations for the LocalTime web service are automatically
listed. In the example there is only one operation, but a web service may have
multiple operations available.
15 Choose LocalTimeByZipCode from the operations drop-down list.
Figure 12-33: If Action Tab for the WSZipToTime Filter
16 Click the Input Mapping button to display the Mapping dialog box.
17 The ROOT element of the XML schema is automatically mapped to the
WSZipToTime form.
18 Select the ZipCode element and the Zip Code field. You created this field in
step 2 on page 327 to contain the zip code.
19 Click the Map button.
Examples ! 329
The ZipCode element (string type) is now mapped to the Zip Code field
(character field designed to contain a string).
Figure 12-34: Input Mapping for LocalTimeByZipCode Web Service
21 Click the Output Mapping button to display the Mapping dialog box.
22 The ROOT element of the XML schema and the WSZipToTime form will be
automatically mapped.
23 Select the LocalTimeByZipCode element and the Time of ZipCode field as
shown in the following figure. You created this field in step 2 to contain the
time.
24 Click the Map button.
The LocalTimeByZipCode element (string type) is now mapped to the Time
of ZipCode field (character field designed to contain a string).
Figure 12-35: Output Mapping for LocalTimeByZipCode Web Service
26 Click Add Action to add the action to the Current Actions pane. See If Action
Tab for the WSZipToTime Filter on page 329.
27 Save the filter.
28 Open an AR System client and log in.
29 Open the WSZipToTime form.
30 Enter data in the required fields.
31 Save your form.
32 Search to open the form in Modify mode.
You created the WSZipToTime Filter to trigger On Modify. See Figure 12-32
on page 328.
33 Enter a zip code in the Zip Code field.
34 Click Save or Submit.
Examples ! 331
The time for the zip code you entered is displayed in the Time of ZipCode
field as shown in the following figure.
Figure 12-36: WSZiptoTime Form in AR System Windows User Tool
35 Try different zip codes.
Example 3: Publishing a Complex Document
In this example you are going to publish a web service with two operations
!
CreatePurchaseOrder that takes PO information as input and returns the
Request ID as output.
!
GetPurchaseOrder that takes the PO ID as input and returns the
information of that Purchase Order.
1 Create an XML schema (.xsd file) containing the elements for your Purchase
Order.
2 Call it PO.xsd. An example follows.
<?xml version="1.0" encoding="UTF-8"?>

<xs:schema targetNamespace="http://tempuri.org"
xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.org"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="PO" type="PurchaseOrder">
<xs:annotation>
<xs:documentation>Comment describing your root
element</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="PurchaseOrder">
<xs:sequence>
<xs:element name="POID" type="xs:string"/>
<xs:element name="CompanyName" type="xs:string"/>
<xs:element name="Description" type="xs:string"/>
<xs:element name="PhoneNumber" type="xs:string"/>
<xs:element ref="Items"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="LineItem">
<xs:sequence>
<xs:element name="ItemName" type="xs:string"/>
<xs:element name="Quantity" type="xs:int"/>
<xs:element name="ItemId" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:element name="Item" type="LineItem"/>
<xs:element name="Items">
<xs:complexType>
<xs:sequence>
<xs:element ref="Item" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Creating Your Forms
Create two new forms, the ones in our example are called PO and LineItems.
1 Create the form named PO, which is the parent form, and add four character
fields, PO ID, Company Name, Description, and Phone Number.
Examples ! 333
2 Hide all the other fields on the form.
3 Give a default value to Submitter and Short Description fields, since they are
required fields.
Your form should look similar to the one shown in the following figure.
Figure 12-37: PO Form
4 Choose Form > Form Properties from the Menu bar to open the Form
5 Click the Indexes tab.
6 Select PO ID, and add it to the Index On pane.
7 Check the Unique box.
In this example, we are using PO ID as the primary key. However, in most
situations you would use Request ID as the primary key. In those situations,
you do not need to create the PO ID field, and you do not need to perform
step 4 to step 7.
8 Save the form.
9 Create the form named LineItems, which is the detail form, add character
fields, LineItemPOID, ItemID, ItemName and an integer field Quantity.
This LineItemPOID is going to be the Foreign Key and ItemID is going to be
the distinguishing key.
10 Hide all the other fields.
11 Set the Data Length of the LineItemPOID and ItemID fields to 40.
12 Give a default value to the required fields Submitter and Short Description
(these are hidden).
13 Save your form.
Figure 12-38: LineItems Form
14 Choose Form > Form Properties from the Menu bar to open the Form
15 Click the Indexes tab.
16 Add LineItemPOID and ItemID to the Index On pane.
17 Make the combination of these two fields (LineItemPOID and ItemID)
unique.
Making the distinguishing key and the Foreign Key unique maintains the
consistency with the data, even if the data is submitted with the other tools
on this form.
18 Save the form.
Examples ! 335
The following steps, step 19 to step 27 are optional. They will enable you to
view the line items of the corresponding Purchase Order in the same form.
19 Open the PO form.
20 Add a table field by right-clicking and select Table Field from the context
menu.
21 Double-click on the table field to open the Field Properties dialog box.
22 Click the Table Property tab.
23 Select the LineItems from the Forms list.
24 Add ItemID, Item Name and Quantity to the Field As Column pane.
25 Enter the qualification $PO ID$ = ’LineItemPOID’ in the Qualification field.
This ensures that the PO ID of the parent form PO matches the
LineItemPOID of the form LineItems.
Figure 12-39: Table Property Tab of the Field Properties Dialog Box
If you had used Request ID as your primary key, choose this qualification
instead:
$Request ID$ = ’LineItemPOID’
26 Close the Field Properties dialog box.
Figure 12-40: PO Form with a Table
27 Save your form and close it.
Creating Your Web Service
1 Right-click on the parent form name (PO) in the Server Window (see
Figure 12-27 on page 323, if necessary).
2 Select Create Web Service.
The Create Web Service dialog box appears.
The AR System automatically populates the Name and the Base Form field
with your parent PO form name.
3 Select document literal from the Service Type field, if it is not selected.
4 Enter the path, or browse to your PO.xsd file in the XML Schema field.
5 Click the Load button, and OK at the confirmation dialog box.
6 Enter the label wsPO in the Label field.
7 Enter “Web Service to Create and Get a Purchase Order” in the Description
field.
8 Select OpGetList in the Operations List and click Remove.
9 Select OpSet in the Operations List and click Remove.
10 Select OpCreate in the Operations List.
Examples ! 337
OpCreate appears in the Name field.
11 Select OpCreate in the Name field and replace it with CreatePurchaseOrder
in the Name field.
12 Click Modify.
The new name appears in the Operations List.
13 Do the same with OpGet and rename it to GetPurchaseOrder.
Figure 12-41: The Create Web Service Dialog Box for Purchase Order
Mapping for the CreatePurchaseOrder Operation
1 Select CreatePurchaseOrder in the Operations List.
2 Click the Input Mapping button.
The Mapping Dialog box appears.
3 Select the XML Schema radio button.
4 Click the Choose button.
5 Click OK at the warning message that your existing mappings will be
replaced.
6 Choose Purchase Order as the start element in the Choose start element
dialog box, and click OK.
Figure 12-42: The Choose Start Element Dialog Box for Create PO Web Service
Examples ! 339
In the Mapping Dialog Box, only PO form fields are displayed in the Forms
pane, the XML Schema elements and complex types appear in the XML
Schema pane, as shown in Figure 12-43 on page 340.
Figure 12-43: Mapping Dialog Box for PO Web Service Input
7 Click the selection arrow on the Forms field.
8 Select the form LineItems and click Add.
The form name and the fields appear below the parent form in the Forms
pane.
9 Click on the form name PO in the Forms list and ROOT in the XML Data
Type list.
10 Click Map.
The Define form mapping dialog box appears.
11 Select PO ID as the Primary Key (Field to identify XML document uniquely.
The default value is Request ID).
Figure 12-44: Define Form Mapping Dialog Box for Creating PO Web Service
13 Map the other fields on the PO form to XML elements and complex types as
shown in the following table.
Forms and Fields
XML Elements and Complex Field to identify
Types
xml document
uniquely
PO
ROOT/PO
PO ID
POID
Description
Description
Phone Number
PhoneNumber
Company Name
CompanyName
PO ID
14 Select the LineItems form from the Forms pane and Item from the XML Data
Type pane.
15 Click Map.
The Define Form Mapping:Establishing master detail relation form appears.
16 Select ItemID as the Field to distinguish this detail from others.
Examples ! 341
17 Select LineItemPOID as the Field to link the parent form with current form
(Foreign Key).
Figure 12-45: Define Form Mapping: Establishing master detail relation
18 Click OK.
19 Map the fields as shown in the following table.
Forms and Fields
XML Elements and
Complex
Types
Field to distinguish Field to link
this detail item
the parent
from others
form with
current form
(Foreign Key)
Line Items
ROOT/Items/Item
ItemID
Item Name
ItemName
Quantity
Quantity
ItemID
ItemId
LineItemPOID
21 Click the Output Mapping button to open the Mapping dialog box.
!
The Customized radio button will be selected.
!
PO and ROOT will be mapped with Request ID as the primary key.
22 Select PO from the Forms pane (and ROOT from the XML Data Type pane
if it is not selected).
23 Click Unmap.
24 Select PO and ROOT again.
25 Click Map.
The Define form mapping dialog box will open.
Figure 12-46: Define Form Mapping Dialog Box for PO Output Mapping
26 Select PO ID as the Primary Key.
27 Select Request ID in the Forms pane and the XML Data Type pane. (It is the
only output field.)
28 Click Map.
Figure 12-47: Output Mapping Dialog Box for PO Web Service
29 Click OK to close the Mapping Dialog box.
Examples ! 343
Note: Make sure the web service that you created has public permissions.
You will see a warning message if your permissions are not set to
public. To do this, select the Permissions tab in the Create Web Service
dialog box, select Public and click Add.
Mapping for the GetPurchaseOrder Operation
1 Select GetPurchaseOrder from the Operations List.
2 Click the Input Mapping button.
The Mapping Dialog box appears.
3 Leave the XML Data Type Source as Customized.
4 Click the Generate and Map button.
5 Click OK at the warning message that your existing mappings will be
replaced.
6 Select PO and ROOT and UnMap.
7 Select PO and ROOT again and Map.
8 Select PO ID as the Primary Key (Field to identify XML document uniquely,
or typically, Request ID).
Figure 12-48: Define Form Mapping Dialog Box for GetPurchaseOrder Web Service
10 In the XML Data Type pane, delete all the elements except PO_ID by right
clicking on the field name and selecting Cut from the context list.
11 Select PO ID in the Forms pane and PO_ID in the XML Data Type pane.
12 Click Map.
Your Mapping dialog box should look similar to the following figure.
Figure 12-49: The Input Mapping for the GetPurchaseOrder Example
14 Remove the qualification in the Qualification bar in the Web Services dialog
box and replace with the following:
’PO ID’=XPATH(/ROOT/PO_ID)
You can either type the entry, or use the arrow at the right of the
Qualification bar.
a Select the PO > PO ID
b Press =
c Select XPath.
The Choose XPath dialog box opens.
d Select PO_ID and click OK.
Examples ! 345
15 Click the Output Mapping button to open the Mapping dialog box.
16 Select the XML Schema radio button.
17 Click the Choose button.
The Choose start element dialog box appears.
18 Select PurchaseOrder as your start element and click OK to close the dialog
box.
19 Select PO and ROOT again.
20 Click Map.
The Define form mapping dialog box will open.
Figure 12-50: Define Form Mapping Dialog Box for GetPurchaseOrder Output
Mapping
21 Select PO ID as the Primary Key and click OK.
22 Map the other fields on the PO form to XML elements and complex types as
shown in the following table. (However, you would not map Request ID if
you were using it as the Primary Key.)
Forms and Fields
XML Elements and Complex Field to identify
Types
xml document
uniquely
PO
ROOT
PO ID
POID
Description
Description
Phone Number
PhoneNumber
Company Name
CompanyName
PO ID
23 Select the LineItems form from the Forms pane. and Item from the XML
Data Type pane.
24 Click Map.
The Define Form Mapping:Establishing master detail relation form appears.
25 Select ItemID as the Field to distinguish this detail from others.
26 Select LineItemPOID as the Field to link the parent form with current form
(Foreign Key).
Figure 12-51: Define Form Mapping: Establishing master detail relation
27 Click OK.
28 Map the fields as shown in the following table.
Forms and Fields
XML Elements and
Complex
Types
Field to distinguish Field to link
this detail item
the parent
from others
form with
current form
(Foreign Key)
Line Items
ROOT/Items/Item
ItemID
Item Name
ItemName
Quantity
Quantity
ItemID
ItemId
POID
You will see a warning message if your permissions are not set to
public.
Viewing Your WSDL for the PO Web Service
1 Click the WSDL tab on your Web Service dialog box.
Examples ! 347
server name, appears in the URL.
Figure 12-53: WSDL File for CreatePurchaseOrder Web Service
Enter your name and password at the prompt, if necessary, and click Login.
Your WSDL file is displayed in the View field window as shown.
When you invoke the CreatePurchaseOrder Web Service, the Request ID will
be returned if the Web Service has been successful.
Example 4: Consuming a Complex Document
In this example we are going to access the PO web service you created in
Example 3, and get a purchase order and a line item record with the use of
the Set Fields Web Service filter.
For information on setting your environment to consume a web service
ceated on the same AR System server, see Consuming a Web Service Published
on the Same AR System Server on page 292.
Creating Your Forms
1 Create two new forms, following the procedure in Example 3, step 1 to
step 27, but name your forms POClient and LineItemsClient.
Your LineItemsClient form should look similar to the one shown in the
following figure.
Figure 12-54: LineItemsClient Form
Examples ! 349
Your POClient form should look similar to the one shown in the following
figure.
Figure 12-55: POClient Form
3 Click Filter and OK to display the Create Filter dialog box, Basic tab.
4 Enter a Name for the filter, POClient.
5 Check the form POClient to use as the base form.
6 Check Execute On Submit.
Figure 12-56: Create Filter Dialog Box for POClient Filter
8 Select Set Fields from the New Action field list.
9 In the Server name field, select the name of your Server on which the Web
Service filter plugin is installed.
10 Select WEB SERVICE in the Read Value for Field From field.
11 Type the path to your WSDL file in the Choose WSDL field, or browse to
select. Your URL may look like this: http://studio/arsys/WSDL/studio/PO, or
you can type the path to a local WSDL file, as shown in Figure 12-57 on
page 352.
12 Click Load.
13 The name of the web service (PO) is displayed on the dialog box under the
Web Service heading.
The available operations for the PO web service are automatically listed.
Examples ! 351
14 Choose GetPurchaseOrder from the Choose Operations drop-down list.
Figure 12-57: If Action Tab of the Create Filter Dialog Box
Input Mapping
1 Click the Input Mapping button to display the Mapping dialog box.
The ROOT element of the XML schema and the POClient form are
automatically mapped as shown in the following figure
.
Figure 12-58: Input Mapping for POClient Consuming Web Service
2 Select ROOT and POClient and click Unmap.
3 Select ROOT and POClient again and click Map (the circles next to these two
items should become solid).
4 Select PO ID as the Primary key in the Define form mapping dialog box.
Figure 12-59: Define form mapping Dialog Box for GetPurchaseOrder
6 In the Mapping dialog box, select PO_ID and PO ID and click Map.
Examples ! 353
Output Mapping
1 In the Create Filter dialog box, click Output Mapping.
2 Select ROOT and POClient and click Unmap.
3 Select ROOT and POClient again and click Map (the circles next to these two
items should become solid).
4 Select PO ID as the Primary key in the Define form mapping dialog box.
5 Map the following elements to fields.
XML Elements and Complex Fields
Types
ROOT
POClient
POID
PO ID
CompanyName
Company
Description
Description
PhoneNumber
Phone Number
6 Add the LineItemsClient form to the Forms pane by clicking the Forms
arrow, selecting the LineItemsClient form and clicking Add.
7 Select Item in the XML Data Type pane and LineItemsClient in the Forms
pane.
8 Click Map.
The Define Form mapping:Establishing master detail relation form opens.
9 Select ItemID for the Field to distinguish this detail item from others.
10 Select LineItemPOID as the Foreign Key.
12 Map the following elements and fields:
XML Elements and Complex Fields
Types
Item
LineItemsClient
ItemName
ItemName
Quantity
Quantity
ItemId
ItemID
Your mapping should look similar to the following figure.
Figure 12-60: Output Mapping for GetPurchaseOrder Consumption
14 In the Create Filter dialog box, click Add Action to add the filter to the
Current Actions pane.
15 Save the filter.
Consuming the Web Service in an AR System Client
1 Open an AR System client and login.
2 Open a new PO form (created in the Publishing Example 3).
3 Enter data in the required fields to create a record, including a PO ID to a
value of 111.
4 Save your record.
5 Open a new LineItems form (created in the Publishing Example 3).
6 Enter data in the required fields to create a record, including a
LineItemPOID to a value of 111.
7 Save your record.
8 Open a new POClient form.
Examples ! 355
9 Enter a value in the PO ID field of 111.
10 Save the form.
You created the POClient filter to trigger On Submit.
If there is no error message, the save was successful.
11 Open the record you created in step 9 in the POClient form.
If the GetPurchaseOrder Web Service was successful, the record is submitted
and contains the same values as those of the record in the PO form whose
PO ID was set to the value 111.
The values corresponding to the record you created in step 6 for the
LineItems form will appear also in the LineItemsClient form.
Viewing and Debugging your Web Service
1 Stop the AR System server.
2 Open the file armonitor.cfg. (Default location: C:\Program Files\AR
System\Conf)
3 Comment out the line similar to:
"d:\ar system\server5.1\arplugin.exe" -i "d:\ar system\server5.1" -m
4 Copy the line and run it in the Command Line.
5 Make sure "Loaded Web Services plugin properly" is displayed.
6 You will see error messages if your web service does not run properly.
13
Understanding the Alert System
CHAPTER
The alert system is used when a filter or escalation Notify action sends
a notification through the Alert mechanism. This chapter describes the
alert system. The following topics are covered:
!
Alert System Architecture on page 358
!
Alert Events Form on page 359
!
Viewing Alerts on page 359
!
CleanupAlertEvents Escalation on page 360
!
Managing Registered Users on page 360
!
Working with Versions of the AR System Prior to 5.0 on page 361
!
Enabling Alerts on the Web on page 361
For information about other methods of notification delivery, see the
Understanding the Alert System ! 357
Alert System Architecture
The alert system consists of the following components:
!
AR System server
!
Alert Events form
!
Alert list on AR System Windows User Tool or the web
!
AR System Alert, an optional Windows program that informs users when
they receive new alerts (This program should not be confused with the
overall Alert system.)
The following figure shows how the alert architecture is structured.
AR System
Creates and processes
alert events through the
Alert Events form.
ALERT
AR System
Windows User Tool
AR System Alert
Web Browser
Informs users when
new alerts arrive.
Displays alert list and
source requests.
Creates and processes
alert events through
the Alert Events form.
Figure 13-61: Alert Architecture
Note: Versions of AR System before 5.0 used a separate Notification server,
but now all alerts are processed on the AR System server. For
information about backwards compatibility, see Working with
Versions of the AR System Prior to 5.0 on page 361.
For information about configuring servers for alerts, refer to the
358 "Chapter 13—Understanding the Alert System
Alert Events Form
If you choose Alert as the notification method when creating a Notify action
for filter or escalation, alerts are recorded as new requests in the Alert Events
form (see the following figure) when that workflow fires.
Figure 13-62: Alert Events Form
The Alert Events form is automatically installed on your server. This form
contains the alert message details and identification information about the
source request.
The Alert Events form and its original fields cannot be deleted. To make the
feature more powerful, you can add new fields and workflow to the form.
Users do not directly interact with this form; they receive alerts through the
alert list in AR System Windows User Tool or through the web.
Viewing Alerts
The alert list in AR System Windows User Tool or on the web displays alerts
from multiple servers. The alert list queries the Alert Events form on servers
in to which the user is logged for AR System Windows User Tool. For web
clients, the alert list queries servers that are configured in the mid tier. For
more information, refer to the Enabling Alerts on the Web on page 361.
Alert Events Form ! 359
Users can manage the alert list, and open the source request. They can view
alerts in the following ways:
!
In AR System Windows User Tool, choose Tools > View Alerts.
!
In a web browser, display a form that contains an alert list field. This
method requires special configuration. For more information, refer to
Enabling Alerts on the Web on page 361.
!
From AR System Alert, open the alert list in AR System Windows User
Tool or the web browser. For information about AR System Alert, see
AR System Alert online help.
If a web user has access to multiple forms that have alert list fields, AR System
Alert uses the first of those forms that appear in its form list. Therefore, if the
user has permission to multiple forms, you cannot always predict which form
will be used. To solve this issue, you can create multiple forms with alert
fields if every group in the system can access only one of the forms. This
option allows you to create forms with different workflow and different fields
for different groups.
CleanupAlertEvents Escalation
The CleanupAlertEvents escalation is automatically created with the Alert
Events form. If enabled, this escalation deletes all alerts that are older than 30
days and are unread.
Initially, the CleanupAlertEvents escalation is disabled. You can enable it and
customize it according to your needs. If you do not need the escalation, you
can delete it from the server.
Managing Registered Users
For the alert system, the AR System server maintains a list of registered users
in memory and a backup copy in the database (in the alert_user table). All
persistent information is stored in the database, so you can back up and
replicate the environment easily.
Versions of AR System prior to 5.0 kept this information in the nfylogin and
nfylogu files.
Working with Versions of the AR System Prior to 5.0
Be aware of the following implications when you upgrade clients or servers.
Upgrading the Server But Not the Clients
An upgraded AR System server can service previous notification clients such
as Remedy Notifier. It supports the RPC calls that older clients make. When
an older notification client registers to receive notifications, the server
queries the Alert Events form for any unsent notifications. The AR System
server sends alerts (notifications) to the client in the same format that the
older notification server did.
When using Remedy Notifier to log in to a 5.x AR System server, the user
must select the Ntfy Svr option of the Accounts dialog box, even though there
is no Notification server. If a specific Ntfy TCP port is specified, it should be
the same as the port number for the AR System server. If you are going
through a firewall, also specify a listen port within the notification client, as
needed.
Upgrading or Installing Clients But Not the Server
When new AR System Alert clients are installed, they cannot connect to
previous Notification servers. The users must install Remedy Notifier to
receive notifications from servers prior to 5.0. If necessary, Remedy Notifier
and AR System Alert can be run on the same machine in a mixed
environment.
Enabling Alerts on the Web
Users who receive alerts may open the alert list on the web instead of in
AR System Windows User Tool. To enable alerts on the web, you must
provide a web-based alert list, and you must set (or instruct users to set)
certain user preferences. You can also install AR System Alert on Windows
clients for additional functionality.
An Alert List form is automatically installed with your server installation. It
is a web view with an alert list field already created. You can add this form to
your web-based applications, or create your own alert list for the web as
described in the following procedure.
Working with Versions of the AR System Prior to 5.0 ! 361
Creating and Publishing a Web-Based Alert List
For more information on how to perform each of the following steps, refer
to the Developing AR System Applications: Basic guide.
1 Create a regular form on one server in your AR System installation where the
mid tier is also installed.
2 Add an alert list field to the form.
3 Create a web view of the form and deploy it.
4 Make this form accessible on the web through a URL.
Alternately, users can open the alert list form from AR System Alert. For
more information, refer to Installing AR System Alert and Configuring Web
Settings (Optional) on page 363.
Enabling a Preference Server for the Web
1 Ensure that one server in your AR System installation is defined as a
preference server.
For more information about preferences, refer to the Configuring AR System
guide and Installing AR System guide.
2 Under General Settings in the AR System Configuration Tool, enter the
name of the preference server used by alert system users.
See AR System Configuration Tool online help for more information.
Configuring User Preference Values for Alerts on the Web
For each user, set the following preferences in the AR System Windows User
Tool Preferences form. These preferences are available on the Web view or
on the Web tab of the Default Administrator view of this form. For more
information about centralized preferences, refer to the Configuring AR
System guide.
1 In the Alert Servers field, enter the name of each server (separated by
commas) from which users receive alerts.
Alerts from these servers will be visible in the web-based alert list. Users do
not need to be logged in to these servers to receive alerts or to display the
originating request.
2 In the Refresh Interval field, enter the number of minutes between each
automatic refresh of the alert list. A setting of 0 indicates no refresh interval.
Each server specified under Alert Servers will be queried for new alerts, and
these alerts will be displayed in the web-based alert list.
Installing AR System Alert and Configuring Web Settings (Optional)
Optionally, use the following procedure to install and configure AR System
Alert on Windows clients. See AR System Alert online help for information
about AR System Alert.
1 Install AR System Alert according to the procedures in the Installing AR
System guide.
2 Start AR System Alert and open the Options dialog box according to the
procedures in AR System Alert online help.
3 In the Alerts tab, select Open Alert List Using Web.
4 In the Server field, enter the name of the AR System server containing the
deployed alert list form.
5 In AR System Administrator, open the server specified in step 4.
6 Open the Server Information window and select the Advanced tab.
7 In the Default Web Path field, specify the URL for the mid tier, such as
http://<host>/<contextpath>.
For example, if your host name is myserver and you used default settings
when installing the mid tier, the default web path is http://myserver/arsys.
When the user clicks the Open Alert List button in AR System Alert, the
system locates the form containing the alert list field on the server specified
in step 4, and opens it in the browser. If more than one form on the server
has an alert list field, the system opens the first form that it finds.
Enabling Alerts on the Web ! 363
14
The AR System ODBC Driver
CHAPTER
This chapter discusses the AR System ODBC (Open Database
Connectivity) driver and its use. ODBC is an SQL-based programming
standard developed by Microsoft, which represents a connectivity
solution that enables AR System to communicate with ODBC clients,
such as Crystal Reports. AR System makes using ODBC clients easy by
providing the AR System ODBC driver, which provides a gateway to
access data defined in AR System forms.
The AR System ODBC driver provides read-only access to data defined
in AR System forms. The interface provided by the ODBC driver is
similar to that provided by the AR System API. Like the API, the driver
does not provide access to the underlying relational database. Instead,
the driver communicates with the AR System server, which in turn
communicates with the database server. When using the ODBC driver,
the AR System access control model (users and groups) is maintained,
and server-side workflow is still triggered.
!
Compatibility with ODBC Clients on page 366
!
Creating Multiple Data Sources on page 366
!
Using Crystal Reports with AR System on page 368
!
Using Microsoft Access with AR System on page 372
!
Using Microsoft Excel with AR System on page 373
The AR System ODBC Driver ! 365
Compatibility with ODBC Clients
Many ODBC clients are available. The AR System ODBC driver provides:
!
Full functionality with Seagate Crystal Reports 8.5, which enables you to
create custom reports with wide-ranging capabilities and provides
additional flexibility in report design.
!
Basic functionality with Microsoft Access.
!
Basic functionality with Microsoft Excel.
Refer to the compatibility matrix on the Remedy web site for additional
information about supported ODBC clients.
Note: With the Seagate 7.0 Info Designer tool (which is not supported), you
may get the ODBC error: Column not found: <column name>, where
<column name> is the table or column name that contains characters
such as dot (.), hyphen (-), plus sign (+), semicolon (;), and so on. This
does not occur with Seagate Crystal Reports Professional 6.0 and 7.0.
However, the workaround is as follows: From the Info Report
Designer, open the generated report, go to the Database > Set Alias
menu, click Set Alias, type in the alias name (the alias of the table that
you are reporting), and rerun the report.
Creating Multiple Data Sources
When you install AR System Windows User Tool or the mid tier, the AR
System ODBC driver (data source) is installed. It is installed with the
AR System Windows User Tool unless you deselect that option during
install. The AR System ODBC data source is configured with your AR System
user name and password, and it accesses AR System with your permissions.
You can designate multiple data sources for one third-party tool, and you can
use a single data source for several third-party tools.
For example, you can create a data source called AR System Report User for
access to AR System through Crystal Reports. When you create this data
source, you might specify Joe User as the AR System user and supply Joe's
password. When you use the AR System Report User data source to access AR
System through Crystal Reports, the AR System permissions are granted to
Joe User. This enables you to set up data sources with multiple levels of
permissions.
366 "Chapter 14—The AR System ODBC Driver
Creating Additional ODBC Data Sources
1 Double-click the ODBC icon in the Control Panel.
In Windows 2000, choose Start > Programs > Administrative Tools to find
the ODBC icon.
2 In the User DSN tab of the ODBC Database Administrator dialog box, select
AR System ODBC Data Source, then click Add.
3 Select AR System ODBC Driver from the Create New Data Source dialog
box, and click Finish.
The dialog box shown in the following figure appears.
Figure 14-1: AR System ODBC Setup Dialog Box
4 Type a unique name for the Data Source in the Data Source Name field.
5 Type the AR System server name for the server to be accessed with this data
source in the AR Server field.
6 Enter a user name to access permissions for this user.
7 Enter the user’s password.
8 Select the Descending Diary Fields check box to designate reverse calendar
order.
9 Select the Use Underscores check box.
If you are using Microsoft Access, spaces and hyphens are not allowed in
object names.
10 Click OK.
Note: To modify an existing data source, select it in the ODBC Data Source
Administrator dialog box, and click Configure. The dialog box shown
above is displayed.
Creating Multiple Data Sources ! 367
Using Crystal Reports with AR System
After you set up predefined reports using Crystal Reports, users can view
them by using AR System Windows User Tool and the Crystal Reports
Display Engine. The Crystal Reports Display Engine is automatically installed
with the AR System Windows User Tool installation. For more details, see
the manual Installing AR System. For information about viewing reports
created with Crystal Reports, refer to the online help in AR System Windows
User Tool.
Note: Before you start creating reports based on AR System forms, ensure
that you follow the SQL standard for naming objects such as forms.
For example, start the form name with an alphabetic or underscore
character. You should especially avoid using a number (such as 2) for
the name of a form. The error ODBC error: Unexpected extra token:
xxx (xxx is the name of the form) might display.
The following procedure describes how to get started designing reports;
however, refer to your Crystal Reports documentation for instructions about
designing reports.
Logging On to the AR System Server from Crystal Reports
1 Open the Crystal Report Designer.
2 Show the Report Gallery, and choose an expert such as Standard.
3 Select SQL/ODBC on the Create Report Expert Dialog > Data Tab.
The Log On Server dialog box appears.
4 Select the Data Source you want to log in to.
For example, select ODBC - AR System ODBC Data Source to select the
default data source.
The AR System ODBC Login dialog box appears.
Figure 14-2: AR System ODBC Login Dialog Box
5 Enter the user’s password.
6 Select the Descending Diary Fields check box to designate reverse calendar
order.
7 Click OK to log in.
The Choose SQL Table dialog box appears.
Figure 14-3: Choose SQL Table Dialog Box
8 Select forms and fields for your report, as described in Selecting Report Fields
in Crystal Reports
Selecting Report Fields in Crystal Reports
When you select report fields, some fields might not be listed that are in your
form. This occurs when the field’s database name is different from its display
label.
Using Crystal Reports with AR System ! 369
For example, a field called Last Name in your form is not shown in the
Database Fields list box in Crystal Reports (the Database Fields list box
appears in the following figure). Instead, the field name Surname might
appear. Each field in a form is identified by a unique database name, not by
the display label that appears in the form.
Note: To identify a field’s database name, open the form in AR System
Administrator, and open the Field Properties dialog box for the field.
The Name field of the Database tab in the Field Properties dialog box
shows the field’s database name.
Selecting Forms and Fields for Crystal Reports
1 Access the Choose SQL Table dialog box, as described in Logging On to the
AR System Server from Crystal Reports on page 368.
2 Click Next to show the Fields tab.
Figure 14-4: Create Report Expert Dialog Box—Fields Tab
3 From the Database Fields list, select fields to include in your report, and click
Add.
Alternatively, you can click Add All to include all the fields.
If you want to remove a field or all fields, click Remove or Remove All,
respectively.
4 Click Preview Report to view your report.
Refer to your Crystal Reports documentation for more details about
designing reports.
Considerations for Join Forms
Crystal Reports allows users to generate reports from multiple tables by
joining the tables together. AR System ODBC Driver does not support this
capability; however, you can achieve the same goal by creating an AR System
join form. After creating the join form, generate a report from it.
If you add two fields having the same database name (such as Submitter) to
a join form, one field’s database name appears as a field ID in Crystal Reports.
Limitations When Using Crystal Reports
This section includes limitations that you should be aware of when using
Crystal Reports.
!
Converting Date/Time Strings to Date Strings—In Crystal Reports you
can specify how Date/Time strings are handled if they are used in your
report. By selecting the Convert to Date option in the Reporting tab of the
File Options dialog box, you are specifying that Date/Time strings from
AR System are to be converted to Date strings in Crystal Reports.
However, if you set this option to convert Date/Time strings to Date
strings, you cannot use the select condition of is equal (in the Select tab of
the Create Report Expert dialog box in Crystal Reports). The AR System
Date/Time field only works with the Convert to String or Keep Date-Time
Type options.
!
Sorting in Lists—Consider that selection fields from AR System are
treated as character types. The sorting in lists in Crystal Reports is based
on display value (New, Assigned, Closed), rather than the numeric values
(0, 1, 2) associated with an enumerated field. This occurs because when
the AR System ODBC driver is used, selection fields with
AR_DATA_TYPE_ENUM data types are mapped to SQL_CHAR data types.
ODBC does not have an equivalent data type.
!
Browsing Data—The Browse Data button in the Fields tab of the Create
Report Expert dialog box in Crystal Reports does not display the Request
ID (or other data) for all the requests.
!
Date—Crystal Reports follows the calendar type from your operating
system, which typically is the Gregorian calendar starting from October
15th 1582. If the date field contains a BC date, this will not be supported
by Crystal Reports.
Using Crystal Reports with AR System ! 371
Using Microsoft Access with AR System
This section includes tips for using Microsoft Access with AR System.
!
Decimal points, hyphens, and spaces are not allowed in table and column
names.
When you set up an ODBC driver for use with Microsoft Access, select the
Use Underscores check box. This check box is shown in Figure 14-1 on
page 367.
!
Table names that are nearly identical such as My.Table and My Table
(names that include decimal points, hyphens, and spaces) are not
differentiated by the driver.
Searching for data in these tables might produce unexpected results.
Rename table and field names that are nearly identical.
!
Maximum size of an entry or data set in Microsoft Access is 2K.
If you encounter the errors Record too large when using the Import Table
option or This form or report is based on a query that exceeds the limit for
data in a single record when using the Link Table option, you must
exclude unnecessary fields from the search or report. Refer to your
Microsoft Access documentation for additional information about
excluding fields.
!
Your Microsoft Access authorized signature and your AR System user
name and password might conflict.
If you notice that the tables or fields disappear (although you have access
permissions) when you are working on reports, it is caused by a login
identification conflict. To resolve this problem:
!
!
Select the same user name and password that you use to log in to AR
System.
!
Turn off the following flag in the Registry and set the value to 0:
HKEY_LOCAL_MACHINE\Software\Microsoft\Jet\3.5\Engines\
ODBC\TryJetAuth
When using Microsoft Access to link tables from a AR System ODBC data
source, you will enter information into several dialog boxes. Do not select
any options from the Select Unique Record Identifier dialog box. Simply
click OK to close that dialog box.
Using Microsoft Excel with AR System
When you create an unqualified query for a diary field in Microsoft Excel, the
data appears with small control characters that appear as small boxes. To
remove the control characters, do the following:
1 Highlight the cells and choose Data > Text to Columns > Next.
2 Click the Treat Consecutive Delimiters as One button.
3 Select Finish.
The diary field text data (not the timestamp) is removed with the control
characters.
Note: Microsoft Excel has a date system that begins January 1st 1900. If your
date field contains a BC date, it will not be supported by Microsoft
Excel.
Using Microsoft Excel with AR System ! 373
15
Using the LDAP Plug-In
CHAPTER
This chapter describes how to use the ARDBC LDAP plug-in to
integrate the AR System with a directory service. This chapter includes
the following topics:
!
About LDAP Plug-in on page 376.
!
Building AR System Forms For Directory Services on page 377.
!
Working with the Distributed Server Option on page 394.
For required configuration, refer to the Configuring AR System guide.
Using the LDAP Plug-In ! 375
About LDAP Plug-in
Light-Weight Directory Access Protocol (LDAP) provides a standard
method for accessing information from a central directory. A common use
for LDAP is user authentication. After a user is set up in the LDAP directory,
that user can log in to any application that supports the LDAP protocol with
the same user name and password. For more information, see the
The AR System Database Connectivity (ARDBC) LDAP plug-in allows you
to access data objects stored in a directory service as if they were entries
stored in a typical AR System form. You can search, modify, and create data
in a directory service using this plug-in. You can also use this data to
participate in workflow as well as to populate character menus and table
fields.
Requirements
Keep the following considerations in mind when using the ARDBC LDAP
plug-in:
!
The LDAP plug-in issues requests to directory services using the LDAP v2
protocol.
!
Attributes consist of either character or integer data. Attachments are not
supported at this time.
!
LDAP does not support transactions. Because of this, once an object is
created, modified, or deleted, the change will not roll back should
subsequent workflow in the AR System server detect an error condition.
!
By default, all attributes have one value. Multi-valued attributes are
supported using a special notation described later in this chapter.
!
The distinguished name and password specified in the ARDBC LDAP
configuration is used when connecting to any directory services
referenced in LDAP search URLs.
!
Only server-based certificates are supported.
376 "Chapter 15—Using the LDAP Plug-In
Building AR System Forms For Directory Services
This section discusses the concepts involved in building forms and workflow
in the AR System to access data stored in a directory service. The following
topics are covered:
!
Organizing Data
!
Mapping an AR System Form to a Collection of Objects
!
Attaching Fields to Object Attributes
!
Identifying Objects
!
Supporting Object Creation
Organizing Data
Data within a directory service is organized differently than traditional
database applications. Traditional database applications organize data within
tables that have a fixed number of columns. Each row in that table represents
a single entity and contains a value for each column that the table defines.
A directory service organizes data as a collection of objects. Each object is
characterized by one or more object classes that define the values, or
attributes, that the object defines. In addition, objects might be grouped into
organizational units.
Because of these differences, there is no one-to-one mapping between
rows/columns/tables and objects/attributes/object classes. The following
table shows relationships among directory service, AR System, and typical
database concepts.
Table 15-1: "Best Fit" Analogies Between Data Sources
Directory Service
AR System
Database
Object class
Form
Table
Attributes
Field
Column
Object
Entry
Row
The following sections describe how to map the directory service and AR
System data sources.
Building AR System Forms For Directory Services ! 377
Note: The examples used in this chapter walk you through the creation of an
AR System form and workflow to create and access objects that belong
to the inetorgperson object class. The form and workflow are
provided with the LDAP plug-in software distribution in the file
named inetorgperson.def. You can import this definition file using
Mapping an AR System Form to a Collection of Objects
A table within a database can be described as a collection of rows. The data
associated with an AR System form is described as a collection of entries.
A collection of objects within a directory service is similar to a collection of
entries within a form or a collection of rows within a table. When working
with a directory service, a collection of objects can be described using a
standard LDAP search URL. An LDAP search URL looks something like this:
ldap://studio/o=remedy.com??sub?(objectclass=inetorgperson)
The LDAP URL shown above contains the following components:
Table 15-2: LDAP URL Components
URL component
What it means
ldap://
Indicates the LDAP protocol.
studio
The directory service host name.
o=remedy.com
The search base name.
sub
The search scope. In this case, sub indicates that
the search applies to the entire sub-tree under
the base name.
(objectclass=inetorgperson)
A filter that selects the objects.
Note: It is recommended that you define the
search URL to retrieve objects that inherit
from a particular object class. You should
not mix unrelated objects (for example,
people and computers). They might have
different sets of attributes, making the search
difficult to manage and administer.
Each object selected appears as an entry in the form.
Note: The LDAP URL standard defines a place to list the object attributes
that are to be returned from the search. This attribute list would
ordinarily fall between the base name and search scope within the
URL. In the previous example no attributes are listed because the
LDAP plug-in ignores the attribute list. Instead, you identify attributes
within the field properties – see Alternative Method of Adding a Field to
Represent the uid (User ID) Attribute on page 383.
Creating a vendor form
This section describes how to create a form and attach it to data stored in a
directory service.
You can request a list of candidate forms or fields (preferred method) or you
can enter the information yourself.
Requesting a List of Candidate Forms or Fields
1 Open AR System Administrator.
2 Choose File > New Server Object, then choose Vendor Form to display the
Create a Vendor Form window.
The Available Vendor Names area displays a list of ARDBC plug-ins that are
installed. The Available Vendor Tables area displays a list of search URLs that
contain all the available object classes for the directory service specified.
3 In the Available Vendor Names list, choose ARSYS.ARDBC.LDAP to select
the LDAP plug-in.
4 In the Available Vendor Tables list, select a search URL.
The Available Columns section displays a list of attribute names for the
object class in the selected table name located at the URL you chose.
You can view and modify the LDAP search URL associated with an AR
System form by clicking the Vendor Information tab in the Form Properties
dialog box.
Creating a Form and Attaching Stored Data
The following steps show an example using the inetorgperson objectclass to
create a form that is associated with a collection of objects in the directory
service.
1 Start AR System Administrator and log in to the AR System server.
4 Select Vendor Form from the list of New Server Objects.
5 Select a vendor name, for example RMDY.ARDBC.LDAP, in the Available
Vendor Names field.
6 Select the LDAP URL in the Available Vendor Tables field that corresponds
to the inetorgperson object class:
ldap://studio/o=remedy.com??sub?(objectclass=inetorgperson)
Figure 15-1: The Create a Vendor Form Window
7 Click the Create button to create the form.
A form with a Request ID field appears.
Figure 15-2: The Create Form Window
8 Choose File > Save Form As to display the Save Vendor Form As dialog box.
9 Enter the form name in the Form Name field and click OK to save the form.
You can modify the LDAP search URL at any time. In the Form Properties
dialog box, you can also specify that the form make use of the ARDBC LDAP
plug-in. Other ARDBC plug-ins will require that you enter a different
plug-in name and might not use an LDAP search URL format to define a
collection of objects.
Figure 15-3: The Form Properties Window Showing the LDAP Search URL
Attaching Fields to Object Attributes
Object attributes are analogous to columns in a database table and to fields
on an AR System form. You add fields to the form and define the attribute
name with which the field is associated.
Adding a Field to Represent the uid (User ID) Attribute in the
inetorgperson Example
1 Right-click in the form.
2 From the submenu, choose Field from
ldap://studio/o=remedy.com??sub?(obejctclass=inetorgperson).
The Add Field dialog box appears.
Figure 15-4: The Add Field Dialog Box
3 Select the field to add.
The field appears on your form.
4 Position the field as required.
5 Double-click the field to open the Field Properties dialog box.
6 Click the Database tab to display the database and vendor properties
associated with the field.
Figure 15-5: The Field Properties Window Showing the Attribute Name
7 In the Name field in the Vendor Information box, enter the attribute name,
uid, in the Vendor Information Name field.
8 Choose File > Save Form to save the field properties.
Alternative Method of Adding a Field to Represent the uid (User ID)
Attribute
1 Open the form to which you want to add a field.
2 Choose Form > Create a New > Character Field to add a character field to the
form.
3 With the new Character Field selected, choose Form > Field Properties to
display the new field’s Field Properties.
Change the Label to User ID as shown below.
Figure 15-6: The Field Properties Window, Display Tab
Figure 15-7: Field Properties Window, Database Tab
5 Choose Required as the Entry Mode.
6 In the Name field in the Vendor Information box, enter the attribute name,
uid, in the Vendor Information Name field.
7 Position the field as required.
Multi-Valued Attributes
Most attributes within an object class are defined to support one value. Some
attributes, however, can have many values. For example, a “person” object
includes a “telephone number” attribute that allows you to specify many
phone numbers. When this attribute is retrieved, the directory service can
return zero, one, two, or any number of telephone numbers as atomic values.
This differs from typical database applications and the AR System in that a
column or field only stores one value. If you want to store two phone
numbers in such an application, you would add a new column or field to
accommodate the additional data.
To resolve this difference between the two data models, you use a special
notation when specifying the attribute name in the Field Properties window.
<attribute name>[*<separator string>]
Values associated with attribute name are concatenated into a single value in
the AR System but separated with separator string. For example, to
concatenate all values associated with the telephoneNumber attribute and
separate each value with a comma you would enter the following as the
attribute name in the Form Properties window:
telephoneNumber[*,]
You could then define workflow to extract, add, or modify values in the
comma-separated list of telephone numbers.
Identifying Objects Uniquely
The AR System uniquely identifies entries within a form through the Request
ID field.
Objects within a directory service define an attribute called the Distinguished
Name (dn) that uniquely distinguishes one object from another. An object’s
distinguished name often consists of one or more other concatenated
attributes, for example:
uid=abarnes,ou=People,o=remedy.com
AR System Request IDs are 15 bytes maximum in length and are assigned by
the AR System when the entry is created. Distinguished names, on the other
hand, can be very long and often do not fall within a 15 byte length
constraint. Because of this, Request IDs do not map directly to distinguished
names.
When designing an AR System form to access data stored in a directory
service, you must determine what attribute will be used to uniquely
distinguish one object from another. This attribute must also be short
enough to fit within the AR System’s 15 byte maximum length constraint.
As an example, you might have two AR System fields associated with one
attribute—the Request ID and the normal data field associated with the data.
For example, in a typical system the uid (user ID) attribute uniquely
identifies objects defined by the inetorgperson object class. You would create
a field for User ID and associate both the Request ID field and the User ID
field with the uid attribute.
Note: This is the only case where you should associate one attribute with
more than one AR System field. Associating an attribute with more
than one field might lead to run-time errors or incorrect behavior.
You can use the uid attribute to uniquely distinguish one entry from another.
In AR System, no two users have the same uid and uids are shorter than 15
bytes.
Assigning an Attribute to the Request ID Field on Your AR System Form
1 Open the form to which you want to add a field.
2 With the Request ID field selected, choose Form > Field Properties to display
the new field’s Field Properties.
You must change the Request ID field on new vendor forms to point to a
unique field on the LDAP server before you can display records.
4 In the Vendor Information box, in a Name field, enter the attribute name,
uid.
Figure 15-8: Field Properties Window, Database Tab for the Request ID Field
At this point, you can open AR System User and search the collection of
objects to which this form is attached.
Supporting Object Creation
Read this section if you want to create new objects in the directory service
using the ARDBC LDAP plug-in. To support the creation of objects using the
ARDBC LDAP plug-in, you must do the following:
!
You must create an AR System field that is associated with the objectclass
attribute. Note that the objectclass attribute is a multi-value attribute.
!
Although entries within the AR System are uniquely identified by the
Request ID, objects within a directory service are uniquely identified by
the dn (distinguished name) attribute. You must create a field associated
with dn and define workflow that will assign a value to it.
!
Many object classes require that you specify values for certain attributes.
These are similar to required fields within the AR System. Any attributes
that are required must also be added to your AR System form.
Object Class
objectclass is a multi-valued attribute that describes all of the object classes
from which an object inherits. Each object class defines a set of attributes. If
an object inherits from an object class, it can have values for those attributes.
An object can inherit from more than one object class; therefore, an object
can have values for all of the combined attributes.
When you create an object, you must specify all of the object classes from
which the object inherits. You must add a character field to your form and
attach this field to the objectclass attribute and use the multi-value attribute
notation mentioned previously.
As all objects associated with an AR System form belong to the same object
classes, you can easily set the default value of the field to the object class list.
For example, the default value for the object class field associated with an
inetorgperson would be:
top,person,organizationalperson,inetorgperson
inetorgperson objects inherit from the top, person, organizationalperson,
and inetorgperson object classes.
As the value does not change for this field, you should make this field Read
Only and may want to make the field Hidden by way of the Field Properties
window.
Distinguished Name
Distinguished Name (dn) is an attribute that is assigned a value generally
through workflow. The workflow will take one or more values and assemble
the value for the dn attribute. Once the dn is assigned at creation, it typically
does not change just as the Request ID does not change in an entry under an
AR System form.
This is done using a filter that executes on a submit operation. You define the
filter to perform a Set Fields operation like the one shown below.
Figure 15-9: Defining a Set Fields Filter Action to Set the DN Attribute
Defining Filters
The last task in this process is to define a filter that will construct the
distinguished name. In our example, an object’s distinguished name looks
something like this:
uid=abarnes, ou=People, o=remedy.com
The following steps show how to create an AR System filter to assemble the
distinguished name using the inetorgperson example.
2 Select Filter from the list of New Server Objects.
3 Enter inetorgperson:create as the filter’s name.
4 Select inetorgperson under the Form Name list.
Figure 15-10: The Create Filter Form
5 Select Submit as an Execute On condition.
Figure 15-11: The If Action Tab
7 Select Set Fields for the New Action
8 Select Distinguished Name for the Name field.
9 Enter the following into the Value field:
"uid=" + $User ID$ + ", ou=People, o=remedy.com"
Figure 15-12: Creating a Set Fields Filter Action
10 Click Add Action.
11 Choose File > Save Filter.
At this point, you can log in to AR System User and open the inetorgperson
task to search and create entries.
Summary of Fields
In the inetorgperson example, the following fields are needed:
Table 15-3: Summary of Fields
Field
Field properties
Distinguished Name
Entry Mode: Optional
Read/Write
Default Value: none
Vendor Information Name: dn
Object Class
Entry Mode: Required
Read Only
Default Value:
top,person,organizationalPerson,inetorgperson
Vendor Information Name: objectclass[*,]
Last Name
Read/Write
Default Value: none
Vendor Information Name: sn
Common Name
Read/Write
Default Value: none
Vendor Information Name: cn
Organization List
Read/Write
Default Value: People
Vendor Information Name: ou[*,]
In this example, the form looks like the following figure.
Figure 15-13: The inetorgperson Form
Working with the Distributed Server Option
This section discusses using the ARDBC LDAP plug-in with the Distributed
Server Option (DSO). The topics covered include the following:
!
Conceptual Overview
!
Directory Service Attributes and Object Classes
!
Enabling Your Data
!
DSO Field Definitions and Properties in the AR System
Note: The features and configuration of DSO are described in detail in the
Distributed Server Option User’s Guide. The examples in this chapter
draw from the case study presented in the previous chapter.
Conceptual Overview
You can use DSO to transfer data between two forms. These forms may be on
the same or on different AR System servers. These forms may contain data
within the AR System’s underlying database or data exposed through the
ARDBC LDAP plug-in.
To take advantage of some DSO features, such as transferring ownership, the
following configuration steps are required:
!
DSO-related attributes and object classes that will be stored with every
object must be defined in the directory.
!
Objects in the directory service to be transferred must belong to the DSO
object classes.
!
AR System forms must include DSO fields.
If you do not intend to take advantage of DSO’s advanced features, such as
transferring entries with ownership, you do not need to perform any
directory service configuration or add DSO fields to your forms as described
later in this section.
Directory Service Attributes and Object Classes
Three object classes are defined to store the DSO field information: dsoBasic,
dsoFull, and dsoAdvanced. These classes correspond to the basic, full, and
advanced fields that you add to your AR System forms. These object classes
are cumulative: for basic fields, you need only the dsoBasic object class; for
full fields, you need dsoBasic and dsoFull; and for advanced, you need all
three object classes.
Objects transferred using DSO must inherit from one or more of these object
classes if you want to take advantage of DSO’s advanced features. Before
enabling your data for DSO transfers, you must configure your directory
service by adding the attribute and object class definitions provided in the file
rmdydso.schema.
Consult your directory service documentation for further instructions.
Enabling Your Data
Once your directory service is aware of the attributes and object classes for
DSO, you need to ensure that every object that you intend to transfer inherits
from one or more of the DSO object classes.
This allows DSO to store data as attributes associated with each of your
objects. For example, when ownership is transferred from one object to
another, the entry that is the owner must record a pointer to the originating
entry down the ownership chain for update and return operations.
An entry that supports the basic set of DSO fields must inherit from the
dsoBasic object class. For example, an inetorgperson object generally
inherits from the following object classes:
top
person
organizationalperson
inetorgperson
Working with the Distributed Server Option ! 395
For the object to support the basic DSO fields, the object would then inherit
from:
top
person
inetorgperson
dsoBasic
For the object to support the full DSO fields, the object would then inherit
from:
top
person
inetorgperson
dsoBasic
dsoFull
For the object to support the advanced DSO fields, the object would then
inherit from
top
person
inetorgperson
dsoBasic
dsoFull
dsoAdvanced
You must convert existing objects to inherit from the DSO object classes and
ensure that newly created objects do the same.
You can convert existing objects using workflow or using tools provided by
your directory service vendor. Using workflow, you can define an escalation
that selects each object and performs a Set Field action to add the appropriate
object classes. The figure that follows shows an example Set Field action to
add advanced DSO fields to an object’s objectclass attribute.
Figure 15-14: Defining a Set Field Action to Modify the Object Class Attribute
You ensure that new entries inherit from these object classes by adding them
to the default value associated with the objectclass attribute. Setting this
value is discussed in the sections Object Class on page 388 and Supporting
Object Creation on page 387.
DSO Field Definitions and Properties in the AR System
You add DSO fields to your AR System forms using AR System
Administrator. The following steps describe how you add these fields.
1 Open the form to which you want to add a DSO field.
2 Choose Form > Distributed Fields to display the Distributed Fields dialog
box.
3 Select the level of DSO fields that you want to add to your form.
You can choose Basic, Full, Advanced, or None (for no DSO fields).
4 Click OK
The fields will be added to your form. Before saving your form you must
associate each field with the proper attribute name. Attribute Names for DSO
Fields lists all of the DSO fields and their respective attribute names.
For each DSO field that has been added to your form, perform the following
steps.
1 Select the DSO field.
2 Choose Form > Field Properties to display the Field Properties dialog box for
the field.
3 Click on the Database tab.
4 In the Name text field, in the Vendor Information box, enter the attribute
name for the field as described in Attribute Names for DSO Fields in Table
1-4.
5 When you have finished setting the attribute names for all DSO fields, select
the form and choose File > Save Form.
Table 15-4: Attribute Names for DSO Fields
DSO Field Name
Attribute Name
Transfer Status
dsoTransferStatus
Update Status
dsoUpdateStatus
Master Flag
dsoMasterFlag
From Request ID
dsoFromRequestId
From Form
dsoFromForm
From Server
dsoFromServer
From Pool
dsoFromPool
To Mapping
dsoToMapping
From Mapping
dsoFromMapping
To Request ID
dsoToRequestId
To Form
dsoToForm
To Server
dsoToServer
Mapping History
dsoMappingHistory
Current Form
dsoCurrentForm
Current Server
dsoCurrentServer
When To Update
dsoWhenToUpdate
Transfer Mode
dsoTransferMode
DSO Field Name
Attribute Name
Duplicate Request ID Action dsoDuplicateRequestIdAction
Max Time To Retry
dsoMasTimeToRetry
Enforce Pattern Matching
dsoEnforcePatternMatching
Require Required Fields
dsoRequireRequiredFields
16
CHAPTER
Using Action Request System from a
Command Line
This chapter describes the three command line interfaces of the AR
System clients: the AR System Administrator command line interface
(aradmin.exe), the AR System Import command line interface
(arimportcmd or arimportcmd.exe), and the AR System Windows User
Tool command line interface (runmacro or runmacro.exe). These
interfaces deliver limited usage capability without a graphical
interface. The command line interface is useful for writing scripts to
perform repetitive operations. Except for aradmin.exe, which runs only
on Windows, all command line interfaces are designed to be run on a
Windows or UNIX platform.
!
Using the AR System Administrator Command Line Interface on
page 402
!
Using the AR System Import Command Line Interface on page 409
!
Using the AR System Windows User Tool CLI on page 414
Using Action Request System from a Command Line ! 401
Using the AR System Administrator Command Line
Interface
This section discusses using the AR System Administrator command line
interface (CLI). It includes guidelines for using the CLI and options.
Guidelines for Using AR System Administrator CLI
Use the following guidelines to run commands from the AR System
Administrator CLI. Commands and options are listed in the Table 16-1 on
page 403.
!
On a machine with AR System Administrator installed locally, set the
current directory to the directory that contains the AR System
Administrator executable aradmin.exe. The default directory is
C:\program files\AR System\. File arguments without a directory path are
created in the current directory.
!
To type AR System CLI commands from any directory, add the AR System
Administrator directory to your system path environment variable. Refer
to Windows documentation for instructions.
!
Every command executed opens a separate AR System session, executes
the command, and logs out.
!
AR System Administrator parses commands in the precedence listed in the
Table 16-1 on page 403. Commands are interpreted in a predictable order
and may not be executed in the order you type them.
!
You cannot perform an action against two servers with one command. For
example, you must issue two commands to export object definitions from
one server and import them into another server.
!
Enclose arguments that contain blank spaces or symbols in quotation
marks.
!
Except for the Synchronize Search Database option (-s), each command
has required arguments. Arguments must follow the associated option.
402 "Chapter 16—Using Action Request System from a Command Line
AR System Administrator Commands and Options
Use the following format when running aradmin.exe. (The items between
square brackets are optional.)
aradmin -u <user_name> [-p <password>] -x <server_name>
[-w <external_authentication string>] [-portnum <TCP_port_number>]
[-e <file_name>] [-i <file_name>]
[-convert [-<option> -f <form_name>]]
[-c <file_name>] [-s][-o [<log_file_name>]] [-reindex]
Table 16-1: aradmin Command Options (Sheet 1 of 4)
Option
Description and Available Nested Options
-u
User name—Required login parameter that identifies the user
account.
-p
Password—Optional login parameter that identifies the user
account. Omit the option if the user account has no password.
-x
Server name—Required login parameter that specifies the server to
log in to.
-w
Authenticator—Specifies the name of an external authentication
string or Windows NT domain. This is related to the Login window’s
Authentication field, which is discussed in the Configuring AR
System guide.
-portnum
TCP port number used to log in when the portmapper is turned off.
Using the AR System Administrator Command Line Interface ! 403
Option
-e
Definition file—Specifies the file to which to export object
definitions from the source server (identified with the -x login
parameter).
Available options:
-a <active_link_name> for an active link
! -A for all active links
! -b <DSO_pool_name> for a DSO pool
! -B for all DSO pools
! -d <DSO_mapping_name> for a single DSO mapping
! -D for all DSO mappings
! -f <form_name> for a form
! -F for all forms
! -g <active_link_guide_name> for an active link guide
! -G for all active link guides
! -h <filter_guide_name> for a filter guide
! -H for all filter guides
! -j <type_ID> <object_name> for extension objects
! -J for all extension objects
! -k <packing_list_name> for a packing list object
! -K for packing list objects
! -l <packing_list.xml> for an XML packing list (requires argument
for xml file name)
! -m <menu_name> for a menu
! -M for menus
! -n <application_name> for an application
! -N for all applications
! -q <escalation_name> for an escalation
! -Q for all escalations
! -t <filter_name> for a filter
! -T for all filters
! -z <web_service_name> for a web service
! -Z for all web services
!
Option
-i
Source file—Specifies the file that contains the object definitions to
be imported to the target server (identified with the -x login
parameter). The -i option requires a <file> argument to identify the
source file.
Available options:
-a <active_link_name> for an active link
! -A for all active links
! -b <DSO_pool_name> for a DSO pool
! -B for all DSO pools in a server
! -d <DSO_mapping_name> for a DSO mapping
! -D for all DSO mappings
! -f <form_name> for a form
! -F for all forms
! -g <active_link_guide_name> for an active link guide
! -G for all active link guides
! -h <filter_guide_name> for a filter guide
! -H for all filter guides
! -inplace to overwrite existing objects, without deleting objects
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
first
-j <type_ID> <object_name> for extension objects
-J for all extension objects
-k <packing_list_name> for a packing list object
-K for all packing list objects
-l <packing_list_name.xml> for an XML packing list
-m <menu_name> for a menu
-M for menus
-n <application_name> for an application
-N for all applications
-q <escalation_name> for an escalation
-Q for all escalations
-t <filter_name> for a filter
-T for all filters
-z <web_service_name> for a web service
-Z for all web services
Option
-convert
Use to convert native views to web views with unique names.
Available options are:
-f <form_name> for a form
! -F for all forms
! -v <view_name> for a single view
! -V for all views
! -option <XML_file_name.xml>
!
-c
Use to obtain configuration details about a server. All configuration
details for the specified server are sent to a file, including information
not normally displayed by AR System Administrator. The -c
command requires a <file> argument to identify the target file.
-s
Use to synchronize the search database.
-o
Use to redirect errors normally displayed within the command line
interface so that they appear in a file. The -o option requires a
<log_file_name> argument.
-reindex
Initiates a full text search re-index. This works the same as the option
under the Full Text Search tab in the Server Information window of
Extension Objects
The syntax for importing or exporting an extension object is as follows:
aradmin.exe /u <user> [/p <password>] /x <server> /e <exportfile>.def (or /i<
importfile>.def) /j <type_ID> “obj1” “obj2” “obj3”
The type IDs for Flashboards:
Flashboards 32794
Data Sources 32795
Variables 32796
Alarms 32797
AR System Administrator CLI Examples
The following are examples of common tasks you might perform with
aradmin.exe.
Exporting Objects from an AR System Server
When you export objects from the server, you export objects to a target file.
You can export all objects for all forms by using the following command
format:
-e <target_file_name> -F
To export objects from a single form, use the following command format:
-e <target_file_name> -f <form_name>
To parse an XML packing list, and export all objects defined in that packing
list, use the following command format:
-e <target_filename> -l <packing_list.xml>
Note: You cannot export server objects that include a percent sign (%) in
their name.
Importing Objects into an AR System Server
When you import objects into the server, you import objects from a source
file. You can import all objects for all forms by using the following command
format:
-i <source_file> -F
To import specific objects from a source file, use the following command
format:
-i <source_file> -f <form_name> -a <active_link_name>
To parse an XML packing list, and import all objects defined in that packing
list, use the following command format:
aradmin -u <username> [-p <password>] -x <servername>
-i <source_file> -l <packing_list.xml>
The -l option parses the XML packing list and imports all objects defined
within the packing list. This option overrides other options in the same
command.
Converting Form Views
You can convert native views to web views by using the following command
formats.
To convert all native views to web views, use the following command format:
aradmin -u <user_name> [-p <password>] -x <server_name> -convert
To convert specific form views, use the following command format:
-v <view_name> -f <form_name>
To convert views using an XML option file to define copy, prefix, and suffix
operations, use this command format:
-option <XML_file_name>
Obtaining AR System Server Configuration Details
Use the -c command to obtain configuration details for a specified AR System
server. You can output all configuration details for the specified server to a
file, including information not normally displayed by AR System
Administrator.
To obtain configuration information for a server, use the following
command format:
-c <file_name>
Synchronizing an AR System Search Database
Use the -s command to synchronize Search Database.
aradmin -u <user_name> -x <server> -s
Using the AR System Import Command Line Interface
This section discusses the AR System Import CLI. Every cross-platform CLI
command opens a separate AR System Import session, executes the
command, and logs out. Therefore, you must log in with every command. If
AR System Import does not find the user name, AR System Import prints the
usage messages and exits.
Note: On Chinese UNIX systems, CSV and ASCII files cannot be imported
if they contain Date/Time fields.
When using the arimportcmd feature on Japanese UNIX systems, convert
the data and .arm mapping files to EUC format before the files are moved
to the UNIX server. (The .arx and .xml data files are already in EUC format
when they are generated in the client tool, but the .csv file is not.
Therefore, the .arm and .csv files must be converted.) Ensure that all of the
data file names and a mapping file name are in English. When moving files
from Windows to UNIX systems, use FTP to ensure a stable transfer.
Running arimportcmd on a UNIX Machine
When running AR System on UNIX and using arimportcmd, you must add
an entry to the library path before running the command. The following
examples describe how to set up the path with a Bourne shell:
AIX
LIBPATH=$LIBPATH:/<ARServer_install_directory>/bin
export LIBPATH
HPUX
SHLIB_PATH=$SHLIB_PATH:/<ARServer_install_directory>/bin
export SHLIB_PATH
Solaris
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<ARServer_install_directory>/bin
export LD_LIBRARY_PATH
Using the AR System Import Command Line Interface ! 409
Importing with Mapping
Importing with mapping refers to running the AR System Import CLI using
a mapping created in AR System Import. The mapping must be created on
Windows because that is the only environment AR System Import runs on
interactively, but once created, the mapping can be used on any platform.
The -m option in the command line determines this mode. For more
information on Import Tool mapping, see Importing Data into AR System
Forms.
You can override certain settings saved in the mapping by using additional
options. In this way, you can use the data mappings you created for one data
file and destination form for imports with a different data file and form
combination.
arimportcmd -u <user_name> -p <password> [-x <server_name>]
[-w <external_authentication string>] [-r <rpc_number>]
[-a <port_number>]-m <mapping_file_name>
-d <mapping_file_directory> [-l <log_file_path>]
[-o <data_file_name>] [-f <destination_form_name>]
Enclose arguments that contain blank spaces or symbols in double quotes.
The following table describes available options.
Table 16-2: AR System CLI Options with Mapping (Sheet 1 of 2)
Option
Description
-u
account. Requires a <user_name> argument.
-p
account. The -p option requires a <password> argument. Omit the
option if the user account has no password.
-x
Server name—Login parameter that specifies the server to log in to.
The -x option requires a <server_name> argument. This option
overrides the server specified in the mapping. If this option is not
specified, the server name in the mapping is used.
-w
Authenticator—Specifies the name of an external authentication
string or Windows NT domain. This is related to the Login window’s
System guide.
Table 16-2: AR System CLI Options with Mapping (Sheet 2 of 2)
Option
Description
-r
RPC program number—Specifies a private server, for example, if a
dedicated import server is available.
If not specified, the default is the admin server 390600.
-a
TCP port number—Identifies the port number for the server. This
value is especially important in a multiple server environment. The
option also identifies a TCD specific port, if chosen.
-m
Mapping file name—Required name of the mapping file to be used.
The name is usually the file name (without an extension).
-d
Mapping directory—Required directory that contains the mapping
file being referenced with the -m option.
-l
Full path name of the log file—Use this option to log details of the
import execution.
-o
Data file name—Name of the file containing data to import. If
specified, this option overrides the data file specified in the mapping.
If not specified, the data file specified in the mapping is used.
-f
Destination form name—Name of the form to import into. If
specified, this option overrides the form specified in the mapping. If
not specified, the form specified in the mapping is used.
Note: The previous -q, -l, and -n options are not in the current version of
AR System Import.
Importing Without Mapping
Importing without using a mapping refers to running the AR System Import
CLI with no mapping definition to instruct how to map fields. This means
that all field values will be mapped using matching field IDs. Accordingly,
only AR Export (.arx) and AR XML (.xml) file formats are supported because
they are the only file formats that include field IDs.
Without a mapping, the server name, form name, and data file name must be
specified in the command line. Mappings are built by querying the server and
the data file.
Use the following format when running arimportcmd. (The items between
square brackets are optional.)
arimportcmd -u <user_name> -p <password> -x <server_name>
[-a <port_number>][-f <destination_form_name>] -o <data_file_name>
[-l <log_file_path>] [-D <duplicate_ID_option>] [-r <rpc_number>]
Enclose arguments that contain blank spaces or symbols in double quotes.
The following table describes available options.
Table 16-3: AR System CLI Options without Mapping (Sheet 1 of 2)
Option
Description
-u
account. Requires a <user_name> argument.
-p
account. Omit if the user account has no password. Otherwise, a
<password> argument is required.
-x
Server name
-a
TCP port number—Identifies the port number for the server. This
value is especially important in a multiple server environment. The
option also identifies a TCD specific port, if chosen.
-f
Destination form name or pair.
A single name indicates that the form name in the source data file
matches the form name on the server.
To specify a pair of names, separate the form names with an equal
sign, without any blank spaces around the equal sign:
“<Destination_form>”=”<File_form>”.
The destination form is the form on the server into which data will
be imported. The file form is the form specified in the data file.
Specifying pairs maps data from one form, specified in the data file,
to a different form, identified on the server.
Multiple pairs can be specified using this option multiple times, for
example:
-t “Target_form_a”=”File_form_b”
-t “Target_form_c”=”File_form_d”
If the -f option is not specified, AR System Import will attempt to
import all data sets in the source data file. For each data set, if a
matching destination form is found on the server, the data will be
imported. If no matching form is found, the data set will be ignored.
-l
Log file name—Use this option to see details of the import execution.
-o
Data file name—Name of the file containing data to import.
Table 16-3: AR System CLI Options without Mapping (Sheet 2 of 2)
Option
Description
-D
Duplicate ID—Defines how AR System Import processes records
that contain request IDs, which duplicate those already in the form.
With this option, you must include one of the following numbers:
! 0: Generate new ID for all records (the default)
! 1: Reject duplicate records
! 2: Generate new ID for duplicate records
! 3: Replace old record with new record
! 4: Update old record with new record’s data
-r
RPC program number—Use this to specify a private server, for
example, if a dedicated import server is available.
If not specified, the default is the admin server 390600.
AR System Import CLI Examples
With Mapping
The following examples show you how you can use arimportcmd with
mapping:
!
!
In the following example, the server name, form name, and data file name
are optional because the mapping file contains the information:
arimportcmd -u <user_name> -p <password> -m <mapping_name>
-d <mapping_file_directory> -l <log_file>
In the following example, the server name, form name, and data file name
override the names in the mapping file. When you use arimportcmd with
mapping, you can override one or more of the three names.
arimportcmd -x <server_name> -u <user_name> -p <password>
-m <mapping_name> -d <mapping_file_directory> -l <log_file>
-o <data_file_path> -f <form_name>
Without Mapping
Without mapping, you must specify the server name and data file name
because there is no mapping file to provide such information.
The -d and -a options are not shown in the following examples, but if you are
working with multiple servers on the same machine, you can use -d for
duplicate record handling and -a to specify a port number.
The following examples show how you can use arimportcmd without
mapping:
!
!
!
In the following example, minimal options are used. The data file specifies
the data file with path to import. If there are multiple data sets, an import
is attempted for all forms.
-o <data_file_path> -l <log_file>
In the following example, the form name determines which set of data
from the data file will be imported to the server. The form name on the
server and the data file should match.
-f formname -o <data_file_path> -l <log_file>
In the following example, an import is being attempted into the form
called A on the server, but the data comes from form B in the data file.
-f "A=B" -o <data_file_path> -l <log_file>
Using the AR System Windows User Tool CLI
The AR System server includes the runmacro utility, which can run a macro
or export data without a GUI, as a background process. The runmacro utility
can be run from filter or escalation workflow, or as a standalone process (that
is, a Windows batch file or UNIX script). The runmacro utility can also be
used by third-party applications to run AR System macros. One limitation of
the runmacro functionality is that it provides no GUI support. Therefore,
runmacro can execute processes that run in the background and complete,
but it cannot perform tasks such as displaying a Results List of a set of
records.
The runmacro command has two formats, which follow. (The items between
square brackets are optional.) Enclose arguments that contain blank spaces
or symbols in double quotes.
!
You can use the original version of runmacro without the output file
option
(-o):
runmacro [-h <home_directory>] [-d <macro_directory>]
[{-x <server_name>} ...] { -e | -i } <macro_name>
[-p <parameter>=<value> ...] [-U <user_name>] [-P <password>] [{-w | -W }
<external_authentication_string>] [-a <port_number>]
!
You can use runmacro with the -o option to use the old arcopy syntax,
which copies the output to a file:
runmacro -o <output_file_name> [{-x <server>} ...] -U <user>]
[-P <password>] [{ -f | -s} <form>] [-t {arx|csv|xml}]
[{-w | -W } <external_authentication_string>] [-a <port_number>]
When exporting data with attachments by using the -o option, the
attachments folder is created in the same directory as the export file. The
attachments folder name uses an integer timestamp (for example,
917732184), and the folder location is specified in the output file name of the
runmacro command.
When creating macros, you can record a login with the proper permissions if
you are performing actions that require those permissions (for example, an
administrator deleting records). If your macro does not record a login, you
must specify login information using the -U option and the -P option (if
necessary).
The following table lists the options to runmacro, which may appear in any
order on the command line.
Table 16-4: runmacro Command Line Interface Options (Sheet 1 of 2)
Option
Description
-o
Output file name—Specifies the name of the file where you want the
data stored. The file is initially truncated, and then all the data is
written to the file (one data set after another).
-h
Home directory—Specifies a path to the <ar_home_dir> directory. If
you do not specify the -d option, runmacro also looks in this
directory for the arcmds directory that contains the macro to be run.
You can create separate home directories for each user who you want
to run a macro. To run a user’s macros, copy the user’s home
directory from the machine where the user runs the AR System
Windows User Tool to the Windows NT or Windows 2000 server,
and specify it with the -h option, or use the -h option to point to the
user’s home directory on the machine where the user runs the
AR System Windows User Tool.
-d
Macro directory—Specifies the directory that contains the macro if
your macro is not in the <ar_home_dir>\arcmds directory or if you
do not have a <ar_home_dir> directory.
Using the AR System Windows User Tool CLI ! 415
Table 16-4: runmacro Command Line Interface Options (Sheet 2 of 2)
Option
Description
-x
Server name—Specifies the name of a server to connect to. This
option may be included more than once to connect to multiple
servers. Use the following format:
-x <server_name>
-e (or -i)
Macro name—Specifies the macro to be run.
-p
Parameter—Specifies a value for a parameter. There may be more
than one -p option in a command line. If the macro specified (using
the -e or -i options) has a parameter, a value can be supplied by
naming that parameter and assigning a value. If the parameter name
or value includes a space or other special character, the data must be
enclosed in quotes to cause proper interpretation of the special
characters. Use the following format for each parameter specified:
-p parameter=value
-U
account. The -U option must be in uppercase.
-P
Password—Optional login parameter that identifies the user account.
Omit the -P if the user account has no password. The -P option must
be in uppercase.
-w (or -W) Authenticator—Specifies the name of external authentication string
or Windows NT domain. This is related to the Login window’s
System guide.
-a
Port number—The port number to which to connect the server.
-f (or -s)
Form name—Specifies the form that will be exported. The -f (or -s)
option can be repeated multiple times if there are several forms to
export.
If multiple servers are selected, each server will be searched for the
form, and the first one found is all that is exported. To control this,
specify only one server environment for the operation.
If the -f (or -s) option is not specified, the system will export all
available regular data forms. It will not export join or external forms.
-t
Type of file to write—Specifies the file type for the output file: arx,
csv, or xml. If not specified, the default of arx is used.
AR System Windows User Tool CLI Example
Assume that you have a Human Resources (HR) application that runs on a
Windows NT or Windows 2000 machine. When a new employee record is
created in the HR application, you want to issue a Service Request to the help
desk to set up an office for the employee. Assuming the HR application has
the ability to issue a command when the new record is created, you would do
the following:
1 Copy the runmacro utility onto the HR application machine. Assume that it
is in the \AR System directory.
2 Record an AR System macro that takes a series of parameters and submits a
new Service Request record. Assume that this macro is called
SubNewServReq.
For information about recording macros, see the AR System Windows User
Tool online help.
3 Create a script file that the HR application calls when a new employee record
is created. The script contains a command such as:
c:\arsystem\runmacro -x server3 -h \arsystem\macros -e SubNewServReq
-p "Submitter"="HR" -p "Employee Name"="$EmpName$"
-p "Employee ID"=EmpID -p "Employee Type"=EmpType -p "Room
Number"=RoomNum
This command would:
a Take the EmpName, EmpID, EmpType, and RoomNum parameters from
the HR application, and use a fixed Submitter ID of HR.
b Substitute them into the parameters in the “SubNewServReq” macro
stored in the HR application directory.
c Connect to the AR System server called server3.
d Create a new Service Request according to the macro definition.
Using the AR System Windows User Tool CLI ! 417
A
Special System Forms
APPENDIX
The AR System server requires certain system-defined forms that serve
to support baseline AR System functionality such as user preferences,
reporting, and access control. These system forms are automatically
installed with AR System. Most cannot be deleted, and if deleted, are
restored with a server restart.
!
Special System Forms for AR System on page 420
Special System Forms ! 419
Special System Forms for AR System
The following table describes forms loaded automatically during installation
of the AR System server. Those forms that have web views are saved with the
locale of en_US. If you need a web view of the form in another locale, open
the web view of the form on a machine set to the locale you require, and save
it.
Form Name
Description
Group Form
Used to create access control groups to which you grant or
deny access to AR System objects.
See the Developing AR System Applications: Basic guide for
instruction on how to use this form.
User Form
Used to define users, their characteristics, and their access
rights within AR System.
instructions on how to use this form.
Preference Forms:
! AR System
Windows User
Tool Preference
! AR System
Windows User
Tool Central File
! AR System
Administrator
Preference
Store user preferences centrally, providing “roaming
profiles” for any AR System user. These forms are loaded
when they are selected in the Select Action Request System
Components dialog box during installation of the AR
System server.
Users can access the forms in AR System Windows User
Tool to view their preferences, which are set through menu
options in AR System Administrator and AR System
Windows User Tool.
Web views of the preference forms are allowed after
deployment of AR System applications to the web, and can
then be used for setting preferences for web clients.
information on how to use these forms. For information
about the fields in the AR System Windows User Tool
Preference form, refer to the Configuring AR System guide.
Report Form
Links reports to forms on the same AR System server that
hosts the Report Form, and provides the structures needed
for granting permissions to run a report for specified
groups. Administrators and individual users may submit
entries to this form.
Refer to the Chapter 6, Creating Reports for the Web and
Exporting Data for instructions on how to use this form.
420 "Appendix A—Special System Forms
Form Name
Description
ReportCreator Form
Provides the interface to create and maintain AR System
native report definition files. This form is a vendor form
using an ARDBC plug-in. The data is actually stored in the
Report form as attachments.
For more information about ARDBC, refer to the AR
System C API Reference Guide.
ReportType Form
Specifies how each type of report (for example, Crystal or
user-defined types) is created, edited, and run. Generally,
only administrators may submit or modify entries in this
form, but user sessions must be able to view the entries.
ReportSelection
Form
Used in workflow to prompt the end users to select a report
to run. This form has no entries.
Remedy Message
Catalog Form
Enables administrators to provide localized versions of
error messages, help text, menus, and other text strings
displayed to users in applications that are customized by
locale. The use of this form can be enabled or disabled.
Refer to the Chapter 5, Localizing AR System Applications
for instructions on how to use this form.
Server Events Form
Contains a record of internal events for a particular server.
Event types that can be recorded include server structure
changes, user and group changes, and server setting
changes. Options for recording server events are set in AR
System Administrator.
Refer to the Chapter 10, Server Events Form for instructions
on how to use this form.
Alert Events Form
Contains alerts that are sent to users. If a notify action of a
filter or escalation sends an alert, the alert text and
reference is stored in this form.
See Chapter 13, Understanding the Alert System for
instructions on how to use this form.
Alert List Form
An Alert List form is a web view with an alert list field
already created. You can add this form to your web-based
applications for viewing lists of alerts on the web.
Special System Forms for AR System ! 421
Form Name
Description
Server Statistics Form Enables the server to automatically store server statistics.
These statistics can then be graphically displayed by client
programs such as Flashboards and used to analyze server
performance.
See the Optimizing and Troubleshooting AR System guide
and the AR System C API Reference Guide for instructions
on how to use this form.
AR System Email
Mailbox
Configuration
Used for configuring all AR System mailboxes.
AR System Email
Templates
Stores the email templates.
AR System Email
User Instruction
Templates
Used to create additional 'User defined Instructions' based
on templates defined in the AR System Email Templates
Form.
AR System Email
Error Logs
Used for storing status and error information.
AR System Email
Security
Used to store configuration information for Security Keys
used in conjunction with incoming email.
AR System Email
Messages
Used for sending emails through a specified mailbox and as
a repository for all incoming emails. Outgoing and
incoming messages are both stored in this form.
AR System Email
Attachments
Used for storing attachments for an email and for
templates. Attachments for incoming messages are also
stored in this form. The system associates the attachment
with a specific email in the AR System Email Association
form.
AR System Email
Instructions
Stores the Instructions, that have been extracted from an
incoming email by the parsing engine.
AR System Email
Instruction
Parameters
Contains information that defines any parameters required
by an instruction, defined in the AR System Email
Instructions form. This form contains fields that define the
parameter type, such as a field or form name, and the
associated value as extracted from the incoming email.
AR System Email
Association
This form is exclusively used to associate either and Email
Message (in the AR System Email Messages form) with one
or more attachments (in the AR System Email Attachment
form), or to associate a template (in the AR System Email
Templates form) with one or more attachments (in the AR
System Email Attachment form).
Form Name
Description
AR System Email
Attachment Join
This form is used by the table fields located on the AR
System Email Messages form and the AR System Email
Templates form to display attachment information. It
ensures the workflow for the forms works correctly,
enabling you to add, delete, or modify attachments
through the forms without having to access the AR System
Email Association form.
AR System Currency This form holds the currency types that are available on a
Codes
server. Each currency code may be activated or inactivated
by checking the Active field on the AR System Currency
Code form. Activating a currency makes it available to the
clients.
AR System Currency An entry in this form overrides the currency labels that
Label Catalog
appear in the Currency Pickers (the menus associated with
currency fields) of AR System Windows User Tool and a
browser.
AR System Currency A join form that clients query to retrieve overridden
Localized Labels
currency labels. There is no interaction with this form.
AR System Currency This form holds the ratios for converting one currency type
Ratios
to another. There will be a ratio for both directions, for
example from USD to Euro and from Euro to USD,
because these conversion rates are sometimes different.
The table can store current conversion rates, as well as
historical ones.
AREA LDAP
Configuration
Form through which the administrator can view and
modify the parameters for the AREA LDAP plug-in. The
parameters are used to query the LDAP enabled directory
service for authentication purposes and user information.
ARDBC LDAP
Configuration
Form through which administrators can view and modify
the parameters for the ARDBC LDAP plug-in. The
parameters are used to establish connections with
LDAP-enabled directory services.
Distributed Mapping. Defines and maintains parameter and data control values
for a specific distributed
mapping.
Distributed Pending
Maintains a queue of pending distributed transfers,
updates, returns, and deletes.
Distributed Pool
Defines and maintains definitions of specific distributed
pools.
Special System Forms for AR System ! 423
Index
A
accrue operator
Advanced Search Bar method 98
full text search 90
QBE method 97
using 97
accrue searches 95, 97
accruing results with FTS 92
active link actions
Call Guide 17
DDE 71
Direct SQL 19, 20
Exit Guide 19
Go To Guide Label 20
OLE Automation 42
Open Window 143, 169
Wait 21
active links
DDE 64, 76
execution order 290
guides interacting with 32
OLE Automation 45–59
selecting, for a guide 25
ActiveX controls, linking to (OLE) 60
adding
method (OLE) 44
source control and 224
adjusting view size 136
Advanced Search Bar 98
advisory mode 217
alert architecture 358
Alert Events form 359, 421
alert list, web-based 361
alerts
escalation 360
viewing 359
appending export files 183
applications, localizing 112
AR Export format 173
AR System Administrator Preference form 420
AR System Alert 363
overview 359
AR System Import
command line interface 409
data mapping 190
fallback mappings 190
import log file 196, 212
importing data and 206–211
preferences, defining 194–205
AR System Message Catalog
form 421
localizing 124
AR System ODBC driver 365
AR System User
Central File form 420
Preference form 420
AR System Windows User Tool
licensing user, full text search 106
macros, third-party applications 65
reports 86
search results, order 93
Index ! 425
backwards compatibility and macros 137, 172
basic settings
guides 23
buttons
Continue 22
open window action and 171
CleanupAlertEvents escalation 360
close all, guides on exit 19
command (DDE) 74
command line interface
AR System Administrator 402
AR System Import 409
AR System Windows User Tool 414
aradmin 402, 403, 407
arimportcmd 413
runmacro 415, 417
comma-separated value (.csv) format 173
compatibility, backwards with macros 137, 172
Configuration Tool
alert system and 362
localizing mid tier 134
reporting 142, 145
configuring, Crystal Reports 368
creating
packing lists 256
report definition file 153
creating localized view 119
Crystal Reports
date/time strings 371
DSN 146
forms and fields 370
join forms 371
login, AR System 368
report fields in 369
setting up 368
sorting in lists 371
using 366
web reporting 146
C
D
Call Guide action 17
change history
guides 27
packing lists 261
source control 234
changes
object 240, 243
server objects 241
user and group 240
viewing 242
character searches 96
data
ar.ini file, DDE time-out settings 74
aradmin
commands and options 403
examples 407
arcache utility 241
architecture, alert 358
arft.log file 105
arimportcmd
examples 413, 417
importing with mapping 410
importing without mapping 411
options 410, 412
UNIX and 409
arreload utility 241
arserverd (arserver) utility 104
arservftd (arfts) utility 104
ARTEXT 125
ASCII format 173, 174
attachments
importing and exporting 193
attachments, importing and exporting 174
attribute names, for DSO fields 398
automating localization 121, 125
automation servers (OLE) 43, 60
B
426 " Index
exporting to file 173
import file formats 192
importing records, methods of 197–198
importing, procedure for 206–211
mapping for import 190
mapping with saved files 211
preparing to import 191
data mapping, default path for 196
data types, web services 316
databases,searching 90
datatype values 253
DDE
action 71
active link execute action 75
active link poke action 75
active links 64, 76
AR System Windows User Tool macros 65
dde.ini configuration 86–88
DoExecMacro topic 66
examples 67, 71–77, 82
execute action 75
executing macros 64
fields, setting values 76
item name 72
keyword 77
macros, samples 71
Microsoft Excel integration 77–82
Microsoft Word integration 82–86
poke action 75
reports 86
request operation result syntax 76
RunMacro function 66
server name for AR System Windows User
Tool 65
service name 72
time-out settings 65, 74
topic name 72
win.ini configuration 66
debug modes, using log files 28
debugging, full text search 105
definition files
editing 160
reports and 151, 152
saving 160
definitions
exporting 179
exporting and importing views 187
file types 178
importing 184
overview of object 178
source control, exporting 225
source control, importing 227
deleting
definitions files 163
method (OLE) 44
objects from source control 230
direct access URLs, reports and 164
Direct SQL, action 19, 20
directory services
defined 377
distinguished name attribute 385
mapping data 378
object attributes in 385
objects in 378
Distinguished Name
defining filters for 389
described 388
distinguished name, defined 385
Distributed Server Option, described 394
document style, web services 266
documents in the AR System 82
DoExecMacro DDE topic 66
double-byte characters 91
DSN 146
DSO fields, attribute names 398
DSO, adding fields for 397
dynamic data exchange. See DDE
E
editing, report definition files 160
email, exporting templates 137
enforced mode 217
environment
source control 216, 219
web reporting 147
escalation actions
Direct SQL 19, 20
Wait 21
escalation, CleanupAlertEvents 360
escalations, execution order 290
Event Details fields 247
events recorded in Server Events form 239
examples
aradmin 407
arimportcmd 413
Index ! 427
DDE requests, assigning values from 77
runmacro 417
execute action (DDE) 75
execution order, active links and filters 290
Exit Guide action 19
exporting
append definition file 183
attachments 174, 193
data to file 173
definitions to source control 225
email templates 137
object definitions 179
overwrite definition file 183
server-independent 182
view definitions 187
views 137
EXTERNAL keyword 170
F
fallback mappings 190
field labels
localizing 122
field labels, localizing 121
field properties, permissions 27
field types
results list 166
table 166
fields
See also individual database by name
attaching to object attributes 382
Crystal Reports 370
database name, identifying 370
Event Details 247
indexing 102, 107
localizing 121
reserved for Server Events 238
values, setting with DDE request results 76
fields, localizing 122
file types
.def 178
.xml 178
files
definition 160
exporting data to 173
import log 212
428 " Index
import types 192
importing, data formats for 192
report 142
filter actions
Direct SQL 19, 20
Wait 21
filters, execution order 290
fomats for importing data files 192
formats
AR Export 173
ASCII 173, 174
comma-separated values 173
XML 173, 174
forms
See also special forms
Alert Events 359
guides (selecting forms for) 24
localizing 112, 119
renaming 186
Report 161
ReportCreator 152
reporting 142
ReportType 147
Server Events 238, 246
FTS. See full text search
full text search
accrue operator 90, 97
administering 102
arft.log 105
arserverd utility 104
arservftd utility 104
capabilities 90, 101
criteria 94
debugging 105
disk space and 108
fields, indexing 102, 107
Ignore Words List 93, 101
indexes 94, 108, 109
Japanese characters 91
licenses 94, 106
limits 101
method 94
modifiers 92
non-full text search fields and 99
operators 91
QBE settings 100
results list, formatting 109
results, weighting 92
search strategies 99
sorting records by weight 93
special characters 100
using 94
wildcards 98
G
genie help 43
Go To Guide Label action 20
Group form, access control 420
groups
changes 240
viewing changes 245
GUIDE keyword 30
guidelines, command line interface 402
guides
active links, interacting 32
active links, selecting 25
basic 23
Call Guide action 17
change history 27
execution, controlling 30
exiting 19
forms, selecting 24
go to label 20
help text 27
how active links interact with 32
labels 20, 24
logging activity 28
looping through table fields 35
naming 24
overview 15
specifications 23
trace 28
using 37
what is a guide? 30
H
Hankaku Katakana searches 91
HARDWARE keyword 42, 72
help
genie (OLE) 43
guides 27
menus 40
packing lists 261
I
Ignore Words List
rebuilding index 104
searches, using in 101
using 93
import in place (source control) 186, 227, 230,
235
importing
attachments 174
data in to AR System 190
data mapping and 190
data, preparing 191
data, procedure for 206–211
definitions from source control 227
fallback mappings for 190
object definitions 184
records, methods of 197–198
source control 186
view definitions 187
indexes
Ignore Words List 104
moving FTS 109
moving, full text search 109
rebuilding 103
size, estimating 108
indexing
fields 107
for full text search 94, 102
installing languages 117
integration
Microsoft Excel with AR System 77
Microsoft Word with AR System 82
source control with AR System 216
item name (DDE) 72
J
Japanese characters in full text search 91
join forms
web services 304
join forms, Crystal Reports and 371
Index ! 429
K
keywords
DDE 77
EXTERNAL 170
GUIDE 30
HARDWARE 42, 72
reports and 156
L
labels
continue button 22
guides and 20, 24
languages, installing 117
LDAP
attaching fields to objects 382
attaching stored data to form 379
defined 376
mapping data 378
object attributes 382
requesting forms or fields 379
URL standard 378
LDAP plug-in, requirements 376
licenses, full text search 94, 106
limits, full text search 101
line items, web services 297
localization, reporting 154, 172
localizing
forms and 119
menus 131
messages 124
mid tier 134
overview 112
process 115
settings 135
user interface 120
log files
arft.log 105
data import log 196, 212
logging activity, guide 28
logging in, Crystal Reports and 368
looping through table fields 35
M
macros
backwards compatibility 172
430 " Index
DDE programming 64, 65
MS Office applications, examples 71
third-party applications 65
mapping data
arimportcmd 410
fields 208
import preferences and 197–198
overview 190
saved files and 211
mapping data in LDAP 378
mapping, web services 269
menus
help text 40
localizing 131
Message Catalog form, AR System 421
message styles 266
messages, localizing 124
methods (OLE) 44
Microsoft
Excel integration with AR System 77
Word integration with AR System 82
Microsoft Access, AR System and 372
mid tier, localizing 134
modes
advisory 217
enforced 217
get mode 230
modifiers, full text search 92
N
naming
guides 24
packing lists 259
nillable attributes, and web services 297
Notification server 358
notifications
AR System Alert 359
web-based alerts 361
Notify action 359
O
object attributes, defined 382
object changes 240, 241, 243
object class, defined 388
object classes, for DSO 395
objectclass attribute 388
objects
adding to source control 224
checking into source control 233
checking out from source control 231
definitions 178
executable, running source control 236
exporting definitions 179
history in source control 234
importing definitions 184
removing from source control 230
source control and 221
status history in source control 234
undoing check out from source control 232
user information in source control 235
within directory service 378
ODBC
AR System ODBC driver 365
clients supported 365
Crystal Reports and 368–371
data sources, adding 366
Microsoft Access and 372
Microsoft Excel and 373
OLE
active links 45–59
ActiveX controls 60
automation servers 60
methods 44
methods, creating 49–58
sample exercise for 47
OLE Automation action 42
Open Database Connectivity. See ODBC
open window action, reporting 143, 169
operations, web services 269
operators, full text search 91
options
aradmin 403
arimportcmd 410, 412
runmacro 415
source control 222
overwrite (export) 183
P
packing lists
basics 259
change history 261
creating 256
help 261
naming 259
overview 255
permissions 261
saving in XML 262
using 256
parameter list (OLE) 44
path (DDE) 74
permissions
fields 27
packing lists 261
phrase searches 95
poke action (DDE) 75
preference forms 420
preferences
AR System Import 194–205
DSN name (reporting) 146
forms 420
reporting 144
preferences, reporting 142
properties, indexing for FTS 107
Q
QBE searches
settings 100
using accrue operator 97
qualifications, reporting 159
query by example. See QBE searches
R
recording events 239
refresh status history in source control 234
reindexing full text search 103
Remote Procedure Call (RPC) style, web services
266
renaming, forms 186
report files 142
Index ! 431
Report form 161
report forms
overview 142
Report 420
ReportCreator 421
ReportSelection 421
ReportType 421
ReportCreator form 152
reporting 166
backwards compatibility 172
Configuration Tool 145
definition files 151, 152
deleting definition files 163
keywords and 156
localization 154
localized 172
macros 172
overview 142
preferences 144
qualifications 159
running on web 163
statistics 157
table and results list fields
table fields 166
web components 142
reports
configuring for DDE 86–88
logging in from Crystal Reports 368
run macro actions 137
ReportSelection form 164
ReportType form 147
request aliases 121, 122
reserved fields for Server Events 238
results list fields, reporting 166
RPC. See Remote Procedure Call 266
run macro
action 137
command 414
runmacro command 414
RunMacro DDE function 66
S
saving, definition files 160
searches
accrue 95, 97
432 " Index
Advanced Search Bar 98
character 96
Ignore Words List, using in 101
phrase 95
QBE 97
special characters 100
strategies 99
wildcards 98
word stems 98
Server Events form 237, 421
automatic generation 238
datatype values 253
events that can be recorded 239
server setting changes 246
Server Events form, workflow and 253
server independent, exporting definitions 182
Server Statistics form 422
server utilities
arserverd (arserver) 104
arservftd (arfts) 104
servers
automation (OLE) 43, 60
DDE name 65
localizing 135
Notification 358
object changes 240, 241, 243
service name (DDE) 72
set fields from web service filter 289
setting up, Crystal Reports 368
settings
Crystal Reports for web 146
QBE 100
Simple Object Access Protocol (SOAP) 266
headers 318
single-byte characters 91
size, adjusting view 136
SOAP. See Simple Object Access Protocol 266
sorting records by weight 93
source control
adding server objects 224
advisory mode 217
checking in definitions 186
checking in server objects 233
checking out server objects 231
copying to .def file 235
enforced mode 217
environment 215, 216, 219
executable, running 236
exporting definitions 225
get mode 230
history of server objects 234
history, viewing 233
import in place 186, 227, 230, 235
importing definitions 227
integration with AR System 216
latest version 234
object properties 217
options 222
removing server objects 230
setting up 218
status history of 234
undoing check out of server objects 232
user information 235
special forms
Alert Events 421
AR System Currency Codes 423
AR System Currency Label Catalog 423
AR System Currency Localized Labels 423
AR System Currency Ratios 423
AR System Email Association 422
AR System Email Attachment Join 423
AR System Email Attachments 422
AR System Email Error Logs 422
AR System Email Instruction Parameters 422
AR System Email Instructions 422
AR System Email Mailbox Configuration 422
AR System Email Messages 422
AR System Email Security 422
AR System Email Templates 422
AR System Email User Instruction Templates
422
AR System Message Catalog 421
Group form 420
preference 420
Report 420
ReportCreator 421
ReportSelection 421
ReportType 421
Server Events 421
Server Statistics 422
User form 420
spreadsheets, in the AR System 77
statistics, reports 157
subadministrator permissions, packing lists 261
T
table fields, looping 35
templates, email 137
third-party applications and macros 65
time-out settings, DDE 65, 74
topic name (DDE) 72
trace modes, guide activity 28
type library information (OLE) 43
U
UNIX, arimportcmd and 409
URL for LDAP 378
URLs, directly accessing report form 164
User form, access control 420
user interface, localizing 120
user preferences, reporting 144
users
AR System Alert 360
changes 240
information (source control) 235
viewing changes 245
utilities
arserverd (arserver) 104
arservftd (arfts) 104
V
Verity Developer’s Kit 91
version, getting latest from source control 234
viewing
group changes 245
server changes 242
server object changes 243
user changes 245
viewing alerts 359
views
adjusting size 136
exporting 137
Index ! 433
exporting and importing definitions 187
localized 119
W
Wait action 21
web reporting
checklist 143
components 142
Configuration Tool 145
environment 147
running reports 163
web service clients 281
web services 265
advanced XML editing 313
AR System Configuration Tool 319
authentication 318
base form 269
choice element 298
complex documents 295
consuming 289
consuming flow 292
create operation 283
creating 268
custom 274
data types 316
default 270
describing 266
examples 322
get operation 299
importing an XML schema 314
join forms 304
line items 297
mapping 269, 293, 300
nillable attributes 297
object properties 307
operations 269, 279, 283
publishing 268
publishing flow 281
set fields from 289
set operation 283, 299
simple documents 293
simple XML editing 306
XML editing 306, 313
XPATH function 286
434 " Index
Web Services Description Language (WSDL) 267,
270, 274
web views
Crystal web settings 146
reporting 144
weight, sorting records by 93
weighting results with FTS 92
wildcards, in full text search 98, 100
windows, Packing List 257
workflow actions
Call Guide 17
DDE 71
Direct SQL 19, 20
Exit Guide 19
Go To Guide Label 20
OLE Automation 42
Wait 21
workflow, Server Events form and 253
WSDL. See Web Services Description Language
267
X
XML
file type 178
formats for exporting 173, 174
saving packing lists in 262
XML editing, web services 306
XPATH function, web services 286
Z
Zenkaku Katakana searches 91

Action Request System 5.1 Developing AR System Applications

Transcription

Similar documents

Mise en page 1

Beamworks promo - Hubens Machinehandel

horsing - Le Bocage Normand

Hajoca Corporation

Jean-Bernard Lemal

Untitled - Content admin

Credit Report Import - Best Case - Best Case Bankruptcy Software

Regions Express Trade LC Enhancement Background Temporary

ScanFile®