The GUI class is used to collect and display the configuration data required for the agent to operate. The user interface will be used by the Workflow Editor and put in a dialog. The Workflow Editor automatically adds the OK and Cancel buttons.

You must extend the DRAgentUI class in your GUI class. The Workflow Editor will create an instance of this class when an agent is dropped or loaded into the workflow. The instance will be kept until the agent is deleted or the workflow is re/unloaded.

Defining the User Interface

The first method that is called is createGUI. Here you create all the user interface components to be used in the dialog.

Initialization and Deinitialization

The initialize method will be called once after the GUI class has created its user interface components. In this method the agent's name and the Workflow Editor environment is available.

The deinitialize method is called once prior to the destruction of the class.

Displaying Configuration Data

The displayConfig method is called every time the agent is double-clicked prior to the dialog display. The method is handed a DRStorable configuration object that is either null, if the agent has not yet been configured, or contains data if it has. The data has to be type casted to the appropriate type before usage.

It is important that all components in the user interface are cleared in this method before they get populated with the supplied data. If not, old data may reside in the Java components if they were previously filled and Cancel was pressed.

A hint is to populate, for instance, combo boxes with data in this method, if they contain environmental data such as database names or route names. This will ensure that these will get updated each time the user interface dialog is displayed. If they are only populated in the createGUI, the workflow would have to be reloaded, or a new agent would have to be dropped in order to refresh these components.

If the agent supports update of running configurations, it should be considered which fields should be possible to update. Making fields available or not for update is done in the following way. First check if the inherited method isDynamicUpdate returns true. If that is the case the fields that should not be available for update should be disabled. The fields that should be available for update should be enabled or disabled depending on their field instance types. If a field has a field instance type other than final, it should be enabled. If the field instance type of the field is final it should be disabled.

Collecting Data

The collectConfig method collects the configuration from the user interface when OK is clicked.

Validation of User Data

Data entered in the user interface is validated when OK is clicked. The data gets validated against the validation rules specified in the configuration class. If a validation error occurs a dialog will be displayed containing the message specified in the configuration class.

It is important that references to Workflow Editor environment entities, such as route names and MIM resources, are also validated. The recommended way of designing, for instance route names selection, is to populate a user interface component in the displayConfig method. That way, the user cannot select one that is invalid. However, when the user interface dialog has been validated and confirmed, the user may change names on routes and on agents invalidating the previous validation. To prevent this, such external entities must be validated again in the Inspectable class.

Online Help

DRAgentUI provides support for documentation in JavaHelp format. The user documentation *.jar file must be installed with the Usage Engine package. There are many vendors that support generating JavaHelp for different source formats. DTK does not provide a documentation framework but just the ability to show the online help. Please see the official JavaHelp documentation for further information.

Once the JavaHelp *.jar file has been installed, the getHelpIdentifier method should be implemented and return a String array where the first element points out the name of the helpset, e g myagent.hs, and the second element, which is optional, points to an identifier within the help package. The helpset files (i e the *.hs files) in the help package must be unique within the system. It is recommended that the helpset itself is named after the agent or similar.

See Documentation for Agent Plugins (5.0) for information about how to create the online help content.

User Interface for Commands

To create a command to interact with an active workflow, the DRCommandUI class should be extended. The Inspectable class must return the class name in the getCommandUIClassName method.

All methods defined in the User Interface for Commands must be implemented in the same way as the corresponding methods in the DRAgentUI class.