"Process Developer’s Guide Netscape Application Server: Process Automation Edition": Defining Data Fields

The Create a New Data Field Dialog Box
The fields you fill out in this dialog box (see Figure 6.1) depend upon whether you are creating a custom data field or a predefined data field. After you add a field, you can define its properties in the Inspector window.

Figure 6.1 The Create a New Data Field dialog box

Creating a Custom Data Field
To create a custom data field, enter values for the following fields:

Name of this Field. The name of the data field. It is also used to name the database column that is going to store this field information. The value of this property should be unique among the data fields that are defined within a given application.

The name can contain only alphanumeric characters with no spaces. It cannot be longer than 18 characters. It's best to use all lower case, and use the underscore character (_) as a separator. Also, do not use a name that is a reserved SQL keyword (for example, select, integer, etc.), or the LiveWire reserved words project, request, server, and client, or the word comment.

Class ID. The class of the field you are creating. Technically, the class ID is the Java component that implements the field's format, but you don't need to understand the Java components unless you want to create your own Class ID. To add your own class IDs, click the Add New Class button and add your class to the drop-down list of class IDs. For information on writing a custom field, see Chapter 18, "Writing Custom Fields."

Creating a Predefined Data Field
To create a predefined data field, enter values for the following fields:

Name of this Field. defines the name of the data field. It is also used to name the database column that is going to store this field information. The value of this property should be unique among the data fields that are defined within a given application.

Template. A predefined field created with default data that you can modify. These templates make defining a field easier if you are inserting a field of a specific type: address, telephone number, or name.

Adding a Data Field
To add a new data field, click either the Add button or the "Add & Define" button.

Use the Add button to add several items in succession, without defining their properties. Each item will be added to the application tree view, but the "Create a New Data Field" dialog box will remain open so that you can add subsequent items. After adding the desired items, you can set their properties by double-clicking them in the application tree view.

Use the "Add & Define" button to add an item and then immediately define it. Each item is added to the application tree view, but the Inspector window also appears.

Setting Field Properties

Data fields are listed in the Data Dictionary folder in the Application Tree View window. To set or modify field properties, follow these steps:

In the application tree view, in the Data Dictionary folder, double-click the field name, or highlight it and click the Inspector icon.

Update the properties.

Some properties are grayed out and you cannot change them. Other properties contain values in angle brackets (<>). Those values are placeholder values. Replace the brackets and the values inside them with your own data.

Close the window. Your changes are saved automatically.

The following properties are available for all fields. In addition, fields have properties determined by their class ID. For more information about those additional properties, see the documentation for those properties.

Data Type. (Required) Defines the data type of the field (how it is stored in the database). Valid values depend on the Field Class ID and include TEXT, LONGTEXT, INT, FLOAT, DATE, DATETIME, and FILE. These data types map directly to the SQL data types with the exception of FILE. For more information, see your database documentation.

Display Name. The name used in Process Express when end users are allowed to search on a field. Use a name that will be clear and meaningful for the end user.

Field Class ID. (read only) This property describes the format of the data field as it appears on the form.

Help Message. A help message associated with a data field. When users click the field in a form, this message will appear as text at the bottom of the browser window (below the scroll bar).

Name. (read only) The data field's name.

Short Description. A description of the field. Currently, this property is unused.

Custom Data Fields with Predefined Class IDs

Use this option to design your own fields using the class IDs that are predefined in Process Builder:

CheckBox

Computed

Date

DateTime

Digital Signature

File Attachment

Java Applet

Java Bean

Password

Radio Buttons

Select List

TextArea

TextField

UserPicker Widget

The following sections describes these class IDs in more detail.

CheckBox
Use this class ID to create fields in the form of checkboxes. In addition to the properties listed in "Setting Field Properties" on page 136, CheckBox fields have the following properties:

Default Value. The default value of the CheckBox field. Valid values are checked and unchecked.

Label. The label that appears to the right of the checkbox. If you would like to create the label by typing it on the form in the form editor, leave this property blank. However, any label you type into this property is automatically included any time you put the field on a form. If you choose to type the label on the form, you need to type it on each form that uses this field.

On click. A script that runs every time the user clicks on a checkbox. The script is client-side Javascript that is associated with the onClick event handler of the field.

Computed
This class ID is for fields whose values are computed by the application, not entered by the users. In addition, users cannot view these fields. If you want the field to be viewable, use a text field instead.

In addition to the properties listed in "Setting Field Properties" on page 136, Computed fields have the following properties:

Allow Search. Specifies if the field can be used as a search criteria. Valid values are true or false.

Default Value. Defines the default value of the field.

Length. A required property that defines the length of the field and the length of the database column that will be used to store values of that field. It must be an integer between 0 and 2000. Use a value between 0 and 255 for the TEXT data type, and between 0 and 2000 for the LONGTEXT data type. If you want the field to be searchable, use the TEXT type.

Date
This class ID lets the user enter and validate a date.

In addition to the properties listed in "Setting Field Properties" on page 136, Date fields have the following properties:

Allow Search. Specifies if the field can be used as a search criteria. Valid values are true or false

Date Format. Represents the formatting of the date. Valid values are DD/MM/YYYY or MM/DD/YYYY.

Default Value. Defines the default value of the field.

DateTime
This class ID lets the user enter and validate a date and time.

In addition to the properties listed in "Setting Field Properties" on page 136, DateTime fields have the following properties:

Allow Search. Specifies if the field can be used as a search criteria. Valid values are true or false

DateTime Format. Represents the formatting of the date and time. Valid values are MM/DD/YYYY HH:MI:SS or YYYY/DD/MM HH:MI:SS. MM is the month, DD is the day of the month, YYYY is the year. HH is the hour, MI is the minutes, and SS is the seconds of the time. Note that the user must put a space between the date and the time.

Default Value. Defines the default value of the field.

Digital Signature
The Digital Signature field is used for signing data. If the user has a certificate, the data is encrypted. For example, you would want a Digital Signature field if a Vice President has to approve a price. In this example, the price field is a user input field that is included in the List of Signed fields for the VP Signature field. When the VP updates the signature field, all the fields listed in the List of Signed fields are signed.

A Digital Signature field can be signed only by one person for a process instance. Once someone signs the field, the next time the field appears, it shows the name of the person who signed it.

In addition to the properties listed in "Setting Field Properties" on page 136, Digital Signature fields have the following properties:

List of Signed Fields. The list of data fields that require an electronic signature. Separate fields with a semicolon (;) between them. All fields included in this list must be on the same form as the Digital Signature field.

File Attachment
Use the File Attachment class ID when the data field is actually a file you want users to attach. This data field provides menus in Process Express that allow end users to upload, download, and view files in a process. Users can use this field if they are accessing Process Express with Netscape Communicator 4.x, or Microsoft Internet Explorer 4.x or 5.x.

A File Attachment field appears in the HTML form as a signed applet. This applet attaches a file to the form. When the end user decides to attach a file to the form, the user clicks the icon for the applet and the applet uploads the file to a special location on the Enterprise Server. All files for a process instance are grouped in the same folder so you can locate and manage them easily.

You specify this location in the URL property of the Content Store. See "Setting Up the Content Store" on page 156 for more information. You specify what kind of file is uploaded in the data field's File Name property. For each kind of file you want users to be able to attach, you must create a separate data field.

Usage Tips for File Attachments
If you want to use file attachments with Secure Sockets Layer (SSL), your server must be SSL-enabled. To use SSL, end users must use Netscape Communicator to access Process Express. For information on how to enable SSL on your server, see the Enterprise Server Administrator's Guide.

If you have Netscape Application Server installed on the same system as Process Express, you will not be able to use Netscape Communicator with file attachments. To avoid this situation, you can install NAS and Process Express on different systems, or you can use Microsoft Internet Explorer to access Process Express.

You must have the Web Publisher or Remote File Manipulation turned on in your Enterprise Server in order to use file attachments.

Warning. You cannot use the Web Publisher's access control functions for Enterprise Servers version 3.5 or earlier. As a result, any user who knows a file's URL can access, read, and modify the content of a file that is stored on Enterprise Server 3.5 or earlier.

File Attachment Properties
In addition to the properties listed in "Setting Field Properties" on page 136, File Attachment fields have the following properties:

Alignment. Defines the alignment of the file representation in the HTML form. Valid values are: CENTER, TEXTTOP, ABSCENTER, ABSBOTTOM. These position the file representation in the HTML form as centered, aligned with the top of the tallest text on the line, aligned with the center of the text, and aligned with the bottom of the text. The text may be moved to accommodate the alignment. Only one line of text is aligned with the data field. Subsequent lines of text appear below the data field. If no alignment value is specified, the alignment is handled by the browser.

Background Color. The background color for the data field display area. Specify an HTML color code in the format #RRGGBB. For example, for pure blue, specify #0000FF. For more information about specifying colors with this format, see the "Color Units" chapter in the HTML Tag Reference at:

http://developer.netscape.com/docs/manuals/htmlguid/index.htm.

Border Width. The thickness of the border to draw around the data field display area in pixels.

Debug Mode. If this is set to true, the data field displays debug information in the browser's Java console.

Display Height. The height in pixels of the data field display area. If you change this height, the size of the icon in the data field does not change. The display area gets more or less background space around the icon.

Display Width. The width in pixels of the data field display area. If you change this width, the size of the icon in the data field does not change. The display area gets more or less background space around the icon. The optimal width is 100 pixels, but this depends on the size of the font and the value of the File name property.