About the script and dialog XML files

This section and the next section use different terminology for dialog boxes and the components they contain, depending on the perspective being described. Dialog box components are items such as buttons, fields, and combo boxes.

When this section and the next section describe dialog boxes and their components from the perspective of a user, terms such as dialog box, button, field, and combo box are used.

When this section and the next section describe dialog boxes and their components from the perspective of their internal representation, the term window element is used. The internal representation of window elements is a hierarchy, where each window element instance is identified by labels. The window element instance also describes its physical characteristics and behavior.

From a user’s perspective, the dialog boxes and their components show different behaviors, where some dialog box elements are hidden until activated. From an internal representation perspective, no such issue of behavior exists. For example, the internal representation of a dialog box looks similar to that of the components it contains, with the exception that the components are nested within the dialog box.

This section describes XML elements that provide AppMon with instructions. These elements have names such as the dialog element and the window element. This document uses a monospaced font to distinguish XML elements. The dialog element identifies a dialog box that an XML script file can cause to be displayed, either intentionally or unintentionally. The window element identifies a window element (dialog box or the components of a dialog box).

This diagram shows the hierarchy of script and dialog XML. A script XML file conforms to the script.xsd schema, which includes (in the XML sense) the window.xsd schema. Similarly, a dialog XML file conforms to the dialogs.xsd schema, which also includes the window.xsd schema.

View full size graphic

Hierarchy of script and dialog XML

A script XML file specifies a series of steps that direct the native application to navigate to certain window elements and then supply responses to those elements. Most responses are text or keystrokes that correspond to the input a user would provide to a field, combo box, or button in the corresponding dialog box.

The intent of the Generate PDF service’s support for script XML files is to direct a native application to print a native file. However, script XML files can be used to accomplish any task that a user can perform when interacting with the native application’s dialog boxes.

The steps in a script XML file are executed in order, without any opportunity for branching. The only conditional test supported is for time-out/retry, which causes a script to terminate if a step does not complete successfully within a specific period of time and after a specific number of retries.

In addition to steps being sequential, the instructions within a step are also executed in order. You must ensure that the steps and instructions reflect the order in which a user would perform those same steps.

Each step in a script XML file identifies the window element that is expected to appear if the step’s instructions are successfully performed. If an unexpected dialog box appears while executing a script step, the Generate PDF service searches the dialog XML files as described in the next section.

Running native applications displays different dialog boxes, which appear regardless of whether the native applications are in a visible or invisible mode. The dialog boxes can be generated by the operating system or by the application itself. When native applications are running under control of the Generate PDF service, system and native application dialog boxes are displayed in an invisible window.

A dialog XML file specifies how the Generate PDF service responds to system or native application dialog boxes. The dialog XML files allow the Generate PDF service to respond to unprompted dialog boxes in a way that facilitates the conversion process.

When the system or native application displays a dialog box that is not handled by the currently executing script XML file, the Generate PDF service searches the dialog XML files in this order, stopping when it finds a match:

• appmon.[appname].additional.[locale].xml

• appmon.[appname].[locale].xml (Do not modify this file.)

• appmon.global.[locale].xml (Do not modify this file.)

If the Generate PDF service finds a match for the dialog box, it dismisses it by sending it the keystroke or other action specified for the dialog box. If the instructions for the dialog box specify an abort message, the Generate PDF service terminates the currently executing job and generates an error message. Such an abort message would be specified in the abortMessage element in the script XML grammar.

If the Generate PDF service encounters a dialog box that is not described in any of the previously-listed files, the Generate PDF service incorporates the dialog box’s caption into the log file entry. The currently executing job eventually times out. You can then use the information in the log file to compose new instructions in the additional dialog XML file for the native application.