8.6.1 Define your Application

The User Agent provides a large number of options for communicating with a JSM application using a variety of protocols, file formats and character encodings. However, if you want to provide the User Agent to your end users, they will use only a small subset of these options. In most cases these options will be the same across all users, and will only change if the application itself changes.

A custom-built User Agent application can hide these options from the end user and allow them to connect to your application by simply clicking a desktop icon and selecting the file to be uploaded.

To do this, you should provide the following items:

It is also recommended that you provide a Help file or set of Help files, in HTML format, to describe your application and the procedure for connecting to it. The help information should be much simpler for the user to follow, and more relevant to your application than the default User Agent Guide supplied with the Integrator software. Refer to 8.5 Build your own Help Files.

You will most likely use the source.open directive in the configuration file. This option specifies how the source file will be found after the configuration file is opened. If you want the user to be able to select any valid source file, use:

 

source.open=*prompt

 

and the user will immediately be offered a file dialog to choose the source file. If the source file has a fixed name, such as order.xml, use:

 

source.open=order.xml

 

and the User Agent will choose that file without prompting the user.

You may also want to include the line:

 

source.send=*prompt

 

which will ask the user whether to send the file, as soon as it is chosen from the file dialog (without selecting Send from the File menu); or alternatively:

 

source.send=*noprompt

 

which will send the file without asking the user.

For example, suppose you have an application that receives an order as a CSV file and returns a receipt as XML, both encoded using UTF-8. You want the user to be able to select any CSV file to upload. You would first create a configuration file like the following:

 
#
# LANSA Integrator Host Information for MyCompany Order Application
#
# Data types & charsets
#
xml=application/xml; charset=utf-8
csv=application/comma-separated-values; charset=utf-8
#
# Source
#
source.open=*prompt
source.send=*prompt
source.filter.extension=csv
source.filter.description=All Sources
source.chooser.description=Comma Separated Values
#
# Response
#
response.filter.extension= xml
response.filter.description=All Responses
response.chooser.description=XML Documents
#
# Transport
#
name=MyCompany Pty Ltd
host=http://www.mycompany.com:80
#
csv.uri=/cgi-bin/jsmdirect?ordercsv
#
# Help
#
help.menu.001=MyCompany Order Help
help.keystroke.001=F1
help.content.001=orderdoc/content.hhc
#
 

This file will be called mycompany.lih in this example.

Next, you would create a shortcut to run the User Agent. With the shortcut configured to start the install directory, the shortcut would have a command line similar to this:

 

javaw â€“Djava.ext.dirs=.\lib\ext com.lansa.jsf.useragent.JSFUserAgent mycompany.lih

 

Finally, you would create a subdirectory called orderdoc under the {current directory}\lib\userhelp directory, and create a set of HTML Help files.Refer to 8.5 Build your own Help Files for more information.

Refer to 8.6.2 What Needs to be Installed? for details about packaging these files for distribution.