Professional Documents
Culture Documents
1
Developing AR System
Applications: Advanced
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.
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 support@remedy.com. If you have
comments or suggestions about this documentation, contact Information Development by email at
doc_feedback@remedy.com.
This edition applies to version 5.1 of the licensed program.
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Overview of This Manual . . . . . . . . . . . . . . . . . . . . . . . . 12
Action Request System Documents . . . . . . . . . . . . . . . . . . . 13
!3
Action Request System 5.1
4"
Developing AR System Applications: Advanced
!5
Action Request System 5.1
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"
Developing AR System Applications: Advanced
!7
Action Request System 5.1
8"
Developing AR System Applications: Advanced
!9
Action Request System 5.1
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
Action Request System 5.1
12 " Preface
Developing AR System Applications: Advanced
Developing AR System Advanced procedures for extending and Administrators Print and
Applications: Advanced customizing AR System applications. PDF
AR-512-DAAG-01
Configuring AR System Server administration topics on Administrators Print and
AR-512-CFG-01 configuring servers and the mid tier, and PDF
maintaining AR System.
Optimizing and Troubleshooting Server administration topics and Administrators Print and
AR System technical essays related to monitoring PDF
AR-512-OTG-01 and maintaining AR System for the
purpose of optimizing performance and
troubleshooting problems.
AR System Database Reference Database administration topics and rules Administrators Print and
Guide related to how AR System interacts with PDF
AR-512-DRG-01 specific databases; includes an overview
of the data dictionary tables.
AR System Distributed Server Server administration and procedures for Administrators Print by
Option Administrator’s Guide implementing a distributed AR System special
AR-512-DSOG-01 server environment with the Distributed order and
Server Option. PDF
AR System C API Reference Guide Information about AR System data Administrators Print by
AR-512-CAPI-01 structures, API function calls, and OLE and special
support. 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 Procedures for installing and licensing Administrators Print and
AR-512-IG-01 AR System. PDF
14 " Preface
1
CHAPTER
Defining Guides and Guide Actions
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 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 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.
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 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
Guide Actions ! 17
Action Request System 5.1
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.
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.
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
Action Request System 5.1
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.
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.
3 In the Guide Label field, enter the name of the label that precedes the active
link or filter with which you want to begin.
If you have not already inserted a guide label before the active link or filter
with which you want to begin, you must modify the appropriate guide object
in this way before you can complete this step.
4 Click Add Action (or click Modify Action).
Guide Actions ! 21
Action Request System 5.1
Use the following sequence of active links to create the typical form fill-in
steps:
! Change Field (Set Focus)
! Message (Prompt)
! Wait
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.”
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.
Defining Guides ! 23
Action Request System 5.1
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.
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 Guides ! 25
Action Request System 5.1
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.
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.
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.
For more information about building and using change history, see
Developing AR System Applications: Basic guide.
Defining Guides ! 27
Action Request System 5.1
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.
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:
Defining Guides ! 29
Action Request System 5.1
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.
“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.
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.
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.
! 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.
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 Interaction
Condition
Submit These conditions can be triggered only when a guide is
After Submit executing a Wait action, or as the result of a Run Macro
action that the guide executes. The conditions are executed in
Search sequence.
Modify
After Modify
Display
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 Interaction
Condition
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 If you close the form on which a guide is running, the guide
Window Close 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 Interaction
Condition
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.
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
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.
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
Applications: Basic guide.
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.
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 Guides ! 39
Action Request System 5.1
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
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.
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
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.
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.
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.
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.
17 Click Add Action (or click Modify Action).
! The OLE Automation action appears in the Current Actions list.
Active Link
Actions
Automation
Servers
Object
Method
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
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.
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.
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.
Note: The following procedures assume that you collapse each list after you
make selections from them.
_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.
_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
Automation from the New Action list.
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
method that you select will be placed below it.
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.
1 Select the last OLE Automation from the Current Actions list, and select OLE
Automation from the New Action list.
By selecting the last action in the list, the next action that you create is placed
below it.
2 Expand _Document Object in the Type Library Information list, and expand
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.
1 Select the last OLE Automation in the Current Actions list, and select OLE
Automation from the New Action list.
By selecting the last action in the list, 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 Application* Application( ) method, and click Add Method.
Application appears in the Parameter List.
4 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.
5 Expand _Application Object in the Type Library Information list, and
expand Methods 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
method that you select will be placed below it.
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.
1 Select the last OLE Automation in the Current Actions list, and select OLE
Automation from the New Action list.
By selecting the last action in the list, 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 Application* Application( ) method, and click Add Method.
Application appears in the Parameter List.
4 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.
5 Expand _Application Object in the Type Library Information list, and
expand Methods 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
method that you select will be placed below it.
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 on page 58.
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.
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.
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.
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
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.
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>
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.
AppName=ARUSER-SERVER
ProgramPath=<path_to_aruser>\aruser.exe DDEcall <path_to_aruser>
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.
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,...>]
[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)
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];
// 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];
HDDEDATA hddeExecute;
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
Smith,Contents=Don’t forget our meeting on Friday)]"
channelNumber = DDEInitiate("ARUSER-SERVER", "DoExecMacro")
DDEExecute channelNumber, RunMacroString$
DDETerminate channelNumber
End Sub
For examples, see Active Link DDE Execute Action on page 75 and Active Link
DDE Poke Action on page 75.
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.
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.
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.
13 Click Add Action (or click Modify Action).
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.
[DDE]
AppResponseTimeout=30
TransactionTimeout=20
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.
For example, you can create an active link button that launches a Windows
application that supports DDE.
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.
The syntax for loading the result of a DDE request operation is:
$DDE$ <service_name>;<topic>;<path_to_program>[;<item>]
$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.
The following examples show AR System active links that use DDE to
integrate AR System with Microsoft Excel and Microsoft Word.
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.
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.
! 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.
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.
! 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.
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.
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.
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.
! 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.
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
[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")]
The following example illustrates a dde.ini file that sends a report to
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]
[WordCurrFormatFile]
Path=c:\msoffice\winword\winword.exe
Application=winword
Topic=system
Format=CurrentFormat
XFRDATA=File
Command1=[FileOpen .Name="%f"]
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.
Thesaurus
This functionality is not implemented in this version of AR System.
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)
Modifier Matrix
The following table outlines which modifiers from the Verity technology
have been implemented in AR System.
Table 4-3: Modifier Matrix
For more information about modifying results list attributes to include FTS
weights, see Displaying FTS Weight in a Results List on page 109.
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.
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.
The search method used by the FTS engine depends on the following factors:
! The original search criteria as entered by the user
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:
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
Action Request System 5.1
For example, if you want to look for the word “hello,” type:
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:
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:
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.
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 FTS ! 97
Action Request System 5.1
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.
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:
This search retrieves all requests that contain the search term right and words
that start with left, such as leftover.
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.
Some searches work better than others. If you receive unexpected results or
a time-out, rewrite your search.
Using FTS ! 99
Action Request System 5.1
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 (\)
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)
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
Applications: Basic guide.
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.
! 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.
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.
For more information about locating your FTS indexes, see Estimating the
Size of the FTS Index on page 108.
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
Configuring AR System guide.
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.
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.
Note: The Index For FTS check box does not appear for servers that are not
licensed for the FTS option.
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.
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.
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.
! 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.
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.
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)
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.
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:
In the default server directory, each language installed has its own resource
file and follows the format: arcatalog_<language_code>.
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.
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
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.
For more information on exporting and importing view definition files, see
Exporting and Importing Definitions on page 179.
7 Verify the layout and field alignments and make adjustments, as appropriate
(see Adjusting View Size in AR System Administrator on page 136).
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
Applications: Basic guide.
Enter
localized text
here.
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
System Applications: Basic guide.
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.
Enter localized
text here.
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).
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.
Fields on the AR System Message Catalog form are relevant to some message
types, but not all.
! 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)
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.
File menus require a separate procedure described in the section that follows.
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:
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.
! 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.
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.
For more details on this setting, refer to the Configuring AR System guide.
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.
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.
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
Developing AR System Applications: Basic guide.
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.
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.
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
Developing AR System Applications: Basic guide.
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
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
Applications: Basic guide.
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.
142 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
5 Define a table or results list field on a form to hold the data that serves as
input for a report.
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.
144 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
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.
146 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
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.
148 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
Table 6-1: Start, Edit, and Create URL Keywords and Descriptions (Sheet 2 of 2)
Keyword Description
$RPTQUERY$ Query string.
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$
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
150 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
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.
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.
152 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
The following figure displays the ReportCreator form with sample entries for
creating a report definition file called UserGroup.
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
Note: The arsys within the URL assumes that you used the installer-supplied
Web Application context path of /arsys/ in ServletExec JSP Engine. If
you used a different context path, change arsys to the name you
specified.
154 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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
156 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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 Backspace
\n Return
\t Tab
\\ Backslash
\<nnn> ASCII character
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.
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 (-).
158 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
! 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.
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.
160 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
The following figure displays the Report form with a sample entry for a
report called UserGroup.
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
reported on is located.
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.
162 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
http://<host_name>/arsys/apps/<locale>/<server_name>/<application_web_
alias>/ReportSelection_WebView.jsp
Note: The arsys within the URL 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.
164 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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)
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
Developing AR System Applications: Basic guide.
166 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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
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.
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.
168 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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.
170 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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
System Applications: Basic guide.
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.
For details on the Ar System Message Catalog entry required for localized
reports embedded in an active link, see External Report on page 130.
172 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
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
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.
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.
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.
174 "Chapter 6—Creating Reports for the Web and Exporting Data
Developing AR System Applications: Advanced
12 Click Save.
176 "Chapter 6—Creating Reports for the Web and Exporting Data
7
CHAPTER
Importing and Exporting Object
Definitions
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 Data into AR System Forms
When you export object definitions to a file, you choose a file type—AR
System definition or AR System XML.
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 All related forms and their form-related items
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 All related forms and their form-related items
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
link guides, filter guides, web services, and distributed
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 Exports as an independent object.
Flashboards Exports as an independent object.
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
Configuring AR System guide.
! 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.
10 Click OK to dismiss the message.
Click Cancel to close the Export Definitions dialog box.
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.
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:
! Select available objects, and then click Add to add objects to the Objects to
Import list.
! Select the object type, and then click Add to add all objects under the
selected type to the Objects to Import 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 Import list.
! Drag and drop objects between the Available Objects and Objects to
Import lists.
! Double-click an object or an object type to move it to the other list.
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.
If the check box is:
! 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.
To export view definitions, follow the same steps outlined in Exporting Object
Definitions to Definition Files on page 179, but choose:
instead of:
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.
instead of:
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
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.
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.
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.
! 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
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.
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
Alert User with Popup Interrupts the import and displays an error message
Dialog (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 If a mapping generates an error, AR System Import
before Alerting User 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
processed according to your preferences. Refer to
Defining Error Handling Preferences on page 198.
! 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
processed according to your preferences. Refer to
Defining Error Handling Preferences on page 198.
! Selected—The problem records are imported with
NULL values in the missing fields.
Note: These settings are affected by field attributes set when fields are
defined. Refer to the Developing AR System Applications: Basic guide.
b For required fields that are not core fields, you have only one option:
Make required fields Defines required fields that are not core fields as
optional during import 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.
AR System Import accepts short or long date formats in the data file, and
ignores leading zeros.
2 Select the appropriate options.
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.
The destination form field names appear in the Form Fields list.
6 Choose File > Open Data File.
The Open Data File dialog box appears.
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.
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.
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.
Loading a Mapping
1 Choose Mapping > Load Mapping.
The Load Mapping dialog box appears.
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.
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.
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.
Figure 9-1: Source Control in AR System (Including Object Properties Dialog Box)
To view detailed source control information about a server object, select the
object, and choose File > Properties.
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.
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.
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.
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.
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.
Run Source Control Starts source control client executable to project page 236
Client directory.
You can hide or view the source control toolbar by choosing View > Toolbars
> Source Control.
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.
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.
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.
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.
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:
! Select available objects, and then click Add to add objects to the Objects to
Import list.
! Select the object type, and then click Add to add all objects under the
selected type to the Objects to Import 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 Import list.
! Drag and drop objects between the Available Objects and Objects to
Import lists.
! Double-click an object or an object type to move it to the other list.
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.
9 Click OK to dismiss the message.
10 Click Cancel to close the Import Definitions dialog box.
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.
When you remove an object from source control, you lose the ability to track
the history of any changes made to the object.
The Server Window lists the user who has checked out the object.
3 Enter any appropriate comments.
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.
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.
4 Click OK.
The object’s .def file is copied into your working directory.
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.
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.
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.
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.
#define AR_SVR_EVENT_CHG_SCHEMA 1
#define AR_SVR_EVENT_CHG_FIELD 2
#define 3
AR_SVR_EVENT_CHG_CHARMENU
#define AR_SVR_EVENT_CHG_FILTER 4
#define AR_SVR_EVENT_CHG_IMPORT 5
#define AR_SVR_EVENT_CHG_ACTLINK 6
#define AR_SVR_EVENT_CHG_ESCAL 7
#define AR_SVR_EVENT_CHG_VUI 8
#define 9
AR_SVR_EVENT_CHG_CONTAINER
#define AR_SVR_EVENT_CHG_USERS 10
#define AR_SVR_EVENT_CHG_GROUPS 11
#define 12
AR_SVR_EVENT_CHG_SVR_SETTINGS
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.
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.
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.
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.
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.
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.
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.
Table 10-2: User and Group Changes
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
In the Event Details fields, semicolons separate multiple items. There are no
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.
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
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
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.
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.)
9 Save your changes.
Note: In this chapter, Packing List window refers to a Create Packing List or
Modify 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 Defines which access control groups have
Permissions 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.
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.
8 Save your changes.
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
Applications: Basic guide.
<?xml version="1.0"?>
<!-- Document Type Definition: Not Found -->
<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.
Message Styles
Web services have two styles of messaging:
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.
http://www.w3.org/TR/SOAP/
http://www.w3.org/TR/wsdl
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;
XML Data
Soap Soap
Processing AR Access/
Request Request DLL Structures Modifi-
cation
API XML2AR
Wrapper
Soap Soap AR
Response Response Structures
AR2XML
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.
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.
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.
This is the form through which your web service operations will function.
6 Select Create Web Service from the pop-up list. The Create Web Service
dialog box appears as shown in the following figure.
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.
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.
! 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:
The New Server Object dialog box opens as shown in the following figure.
! If you leave the field blank, AR System Administrator will create an XML
schema for you using default element names.
10 Click the Options button to display the Advanced Properties dialog box as
shown in the following figure.
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.
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.
Deleting an Operation
a Select the operation from the Operation List.
b Click Delete.
The operation will be deleted from the 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.
You will see a URL for your WSDL file displayed in the field.
18 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.
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.
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
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.
! 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.
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.
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.
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.
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.
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.
‘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”):
<query>
<qualification>’Employee_ID’ > 100</qualification>
</query>
</ROOT>
WebService
ARServer Plugin-Filter
Data XML
access Processing External
AR
and Structures DLL Soap Request Web Service
filter
process
-ing XML2AR Soap
Handler
AR
Structures Soap Response
AR2XML
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.
11 Click the If Action tab or the Else Action tab.
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.
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.
! 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.
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.
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.
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.
PurchaseOrder LineItem
Request ID Description Date Request ID Ln ID Description PO ID
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:
! 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.
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.)
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
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.
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.
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.
14 Click OK to close the Mapping dialog box.
15 Save your web service.
For further information, see the white paper on Limitations available from
the Customer web site at: http://supportweb.remedy.com
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.
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.
POID
Company Name
PO Date PO-People Form
Creator Name
Creator Phone
Line ID
Line Item Form
Item Description
1 Underlined text indicates the Primary Key 2 Text in bold indicates Unique keys
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.
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.
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.
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:
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.
Missing <name> Name is not Name is not This is invalid This is invalid
modified or set to modified or set to XML.2 XML.2
AR default.1 AR default.1
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 ele-
ment 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 un-
changed.
2
When an XML element is missing, in spite of minOccurs being 1, it is in-
valid 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 de-
fault 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.
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
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 op-
eration 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.
empty content.
4
If a field is of character type and it contains an empty string (this is ex-
tremely unusual, it can be done only through the driver program), AR Sys-
tem 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.
use=optional use=required
Name is $NULL$ name=""1 name=""1
Name is "" name=""2 name=""2
<name> Missing name3 Invalid XML 4
is not mapped
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.
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.
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.
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.
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
shown in the following figure.
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.
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.
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)
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.
! 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
<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.
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.
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.
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:
-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>
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
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.
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.
Examples ! 323
Action Request System 5.1
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
Examples ! 325
Action Request System 5.1
7 Replace <midtier_server> with the name of the web server where the mid tier
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
8 Click the View button to view your WSDL file in the window.
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
In AR System Administrator:
Examples ! 327
Action Request System 5.1
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.
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
Action Request System 5.1
The ZipCode element (string type) is now mapped to the Zip Code field
(character field designed to contain a string).
Examples ! 331
Action Request System 5.1
The time for the zip code you entered is displayed in the Time of ZipCode
field as shown in the following figure.
<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>
Examples ! 333
Action Request System 5.1
4 Choose Form > Form Properties from the Menu bar to open the Form
Properties dialog box.
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.
Your form should look similar to the one shown in the following figure.
14 Choose Form > Form Properties from the Menu bar to open the Form
Properties dialog box.
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
Action Request System 5.1
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’
Your form should look similar to the one shown in the following figure.
Examples ! 337
Action Request System 5.1
Figure 12-41: The Create Web Service Dialog Box for Purchase Order
Figure 12-42: The Choose Start Element Dialog Box for Create PO Web Service
Examples ! 339
Action Request System 5.1
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-44: Define Form Mapping Dialog Box for Creating PO Web Service
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
Action Request System 5.1
17 Select LineItemPOID as the Field to link the parent form with current form
(Foreign Key).
18 Click OK.
19 Map the fields as shown in the following table.
Forms and Fields XML Elements and Field to distinguish Field to link
Complex this detail item the parent
Types from others form with
current form
(Foreign Key)
Line Items ROOT/Items/Item ItemID LineItemPOID
Item Name ItemName
Quantity Quantity
ItemID ItemId
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.
Figure 12-46: Define Form Mapping Dialog Box for PO Output Mapping
Examples ! 343
Action Request System 5.1
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.
Figure 12-48: Define Form Mapping Dialog Box for GetPurchaseOrder Web Service
Your Mapping dialog box should look similar to the following figure.
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
Action Request System 5.1
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
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).
27 Click OK.
28 Map the fields as shown in the following table.
Forms and Fields XML Elements and Field to distinguish Field to link
Complex this detail item the parent
Types from others form with
current form
(Foreign Key)
Line Items ROOT/Items/Item ItemID POID
Item Name ItemName
Quantity Quantity
ItemID ItemId
Examples ! 347
Action Request System 5.1
You will see a URL for your WSDL file displayed in the field.
2 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.
3 Click the View button to view your WSDL file in the window.
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.
Note: Make sure the web service that you created has public permissions.
Examples ! 349
Action Request System 5.1
Your POClient form should look similar to the one shown in the following
figure.
Examples ! 351
Action Request System 5.1
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
.
Examples ! 353
Action Request System 5.1
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.
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.
11 Click OK to close the Define form mapping dialog box.
12 Map the following elements and fields:
Examples ! 355
Action Request System 5.1
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
Developing AR System Applications: Basic guide.
ALERT
AR System AR System Alert Web Browser
Windows User Tool 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
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.
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.
Versions of AR System prior to 5.0 kept this information in the nfylogin and
nfylogu files.
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.
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.
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.
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.
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.
8 Select forms and fields for your report, as described in Selecting Report Fields
in Crystal Reports
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.
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.
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.
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.
! 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.
The following sections describe how to map the directory service and AR
System data sources.
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
AR System Administrator.
ldap://studio/o=remedy.com??sub?(objectclass=inetorgperson)
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.
You can request a list of candidate forms or fields (preferred method) or you
can enter the information yourself.
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
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.
4 Click the Database tab to display the database and vendor properties
associated with the field.
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.
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.
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.
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.
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
! 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
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:
Summary of Fields
In the inetorgperson example, the following fields are needed:
! 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.
! 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.
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.
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
For the object to support the basic DSO fields, the object would then inherit
from:
top
person
organizationalperson
inetorgperson
dsoBasic
For the object to support the full DSO fields, the object would then inherit
from:
top
person
organizationalperson
inetorgperson
dsoBasic
dsoFull
For the object to support the advanced DSO fields, the object would then
inherit from
top
person
organizationalperson
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.
For each DSO field that has been added to your form, perform the following
steps.
Extension Objects
The syntax for importing or exporting an extension object is as follows:
Flashboards 32794
Data Sources 32795
Variables 32796
Alarms 32797
To export objects from a single form, use the following command format:
To parse an XML packing list, and export all objects defined in that packing
list, use the following command format:
Note: You cannot export server objects that include a percent sign (%) in
their name.
To import specific objects from a source file, use the following command
format:
To parse an XML packing list, and import all objects defined in that packing
list, use the following command format:
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.
To convert all native views to web views, use the following command format:
To convert views using an XML option file to define copy, prefix, and suffix
operations, use this command format:
Note: On Chinese UNIX systems, CSV and ASCII files cannot be imported
if they contain Date/Time fields.
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
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.
Option Description
-u User name—Required login parameter that identifies the user
account. Requires a <user_name> argument.
-p Password—Optional login parameter that identifies the user
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
Authentication field, which is discussed in the Configuring AR
System guide.
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.
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.)
Option Description
-u User name—Required login parameter that identifies the user
account. Requires a <user_name> argument.
-p Password—Optional login parameter that identifies the user
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.
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
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.
arimportcmd -x <server_name> -u <user_name> -p <password>
-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.
arimportcmd -x <server_name> -u <user_name> -p <password>
-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.
arimportcmd -x <server_name> -u <user_name> -p <password>
-f "A=B" -o <data_file_path> -l <log_file>
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.
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.
Index ! 425
Action Request System 5.1
C D
Call Guide action 17 data
change history exporting to file 173
guides 27 import file formats 192
packing lists 261 importing records, methods of 197–198
source control 234 importing, procedure for 206–211
changes mapping for import 190
object 240, 243 mapping with saved files 211
server objects 241 preparing to import 191
user and group 240 data mapping, default path for 196
viewing 242 data types, web services 316
character searches 96 databases,searching 90
Index ! 427
Action Request System 5.1
Index ! 429
Action Request System 5.1
Index ! 431
Action Request System 5.1
Index ! 433
Action Request System 5.1
exporting and importing definitions 187 Web Services Description Language (WSDL) 267,
localized 119 270, 274
web views
W Crystal web settings 146
Wait action 21 reporting 144
web reporting weight, sorting records by 93
checklist 143 weighting results with FTS 92
components 142 wildcards, in full text search 98, 100
Configuration Tool 145 windows, Packing List 257
environment 147 workflow actions
running reports 163 Call Guide 17
web service clients 281 DDE 71
web services 265 Direct SQL 19, 20
advanced XML editing 313 Exit Guide 19
AR System Configuration Tool 319 Go To Guide Label 20
authentication 318 OLE Automation 42
base form 269 Wait 21
choice element 298 workflow, Server Events form and 253
complex documents 295 WSDL. See Web Services Description Language
consuming 289 267
consuming flow 292
create operation 283 X
creating 268 XML
custom 274 file type 178
data types 316 formats for exporting 173, 174
default 270 saving packing lists in 262
describing 266 XML editing, web services 306
examples 322 XPATH function, web services 286
get operation 299
importing an XML schema 314 Z
join forms 304 Zenkaku Katakana searches 91
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