10 Working with Web Forms

This chapter describes how to create web forms using Oracle Business Process Composer. It provides an introduction to the web forms designer and describes procedures for creating web forms, adding web form controls, and editing web form control properties.

This chapter includes the following sections:

• Introduction to Forms in Oracle BPM

• Introduction to the Web Forms Designer

• Introduction to Web Form Controls

• Introduction to Data Sources

• Walkthrough: Creating a Web Form Using the Form First Method

• Walkthrough: Creating a Web Form Using the Data First Method

• Working with Web Forms

10.1 Introduction to Forms in Oracle BPM

Oracle Business Process Management (Oracle BPM) provides functionality that defines how end users interact with the applications defined by Business Process Model and Notation (BPMN) processes. There are three components within Oracle BPM that work together to define this user interaction: user tasks, human tasks, and forms.

• User tasks: BPMN flow objects that specify where user interaction is required in process.

  Oracle BPM supports different types of user tasks that determine the approval process required.

• Human tasks: Define how users interact with a process-based application.

  They define the user interface, data structures, and connectivity information. See Working with Human Tasks for more information.

• Forms: Define the interface that allow users to interact with your application.

  For business applications created with Oracle BPM these forms are displayed in Oracle Business Process Management Workspace.

Oracle BPM supports the following types of forms:

• Web forms: Define the user interface for a human task.

  They are based on standard technologies, including XHTML, CSS, and Javascript. Web forms are created by process analysts using Oracle Business Process Composer. They are included within a BPM project. This chapter describes how to create and use web forms.

• Oracle Application Development Framework (ADF) task forms: ADF components that define the user interface for a human task.

  ADF task forms are generally designed by process developers. They are created in Oracle JDeveloper and can be added to a BPM project using Oracle BPM Studio.

  See "Getting Started with Human Workflow" in the Developing Business Processes with Oracle Business Process Management Studio for more information.

10.1.1 Introduction to Web Forms

Web forms define the user interface that allow end users to interact with your business processes. Oracle Business Process Composer provides an editor for creating web forms. This enables process analysts to design the way users interact with a business process and also define the underlying data structure required by the application.

Web forms are based on standards, including XHTML, CSS, and Javascript which ensures compatibility across multiple platforms and browsers. At its core, a web form is an XHTML file. However, the form designer allows you to create and design a web form without interacting directly with the XHTML code. After creating a new form, use the web form designer to customize the form's appearance and behavior.

You can add the following to a web form:

• Form controls: Components that you can add directly to a form.

  Form controls define the graphical elements of a web form and their layout. They also display data to users and receive data input. See Introduction to Web Form Controls for information about the types of form controls supported by Oracle BPM.

  When you add, arrange, or remove a form control from a web form, the form editor automatically updates the underlying XHTML code.

• Form rules: Pieces of Javascript code that define the behavior of a web form or web form controls.

  Oracle Business Process Composer provides a form rules editor that allows you to create and edit form rules. See Working with Web Form Rules for more information.

10.1.2 Form First and Data First Design

There are two use cases for creating web forms in Oracle BPM:

• Form first

  In this use case, you create a web form first before any data elements are defined. This allows a business user to define the required user interface using Oracle Business Process Composer. In this use case, user-interface elements are created first without considering the required underlying data model.

  After the form is created, Oracle BPM automatically generates the schema that defines the data required by the web form. This data schema is based on the web form controls added to the web form. When you assign the web form to a human task, this schema is automatically used to define the human task payload.

  See Walkthrough: Creating a Web Form Using the Form First Method for procedural information about this use case.

• Data first

  In this use case, you create a web form based on an existing human task payload. Oracle BPM generates data sources based on the payload. You can add web form controls to a form based on these data sources. One advantage of the data first model is that it allows you to reuse a schema across multiple forms.

  After adding form controls from a data source, use the form designer to rearrange them within the form to define the necessary look and feel of the user interface.

  See Walkthrough: Creating a Web Form Using the Data First Method for procedural information about this use cases.

10.2 Introduction to the Web Forms Designer

Web forms define the user interface of your process based application. Oracle Business Process Composer provides a web form editor for creating web forms.

Using the web forms editor you can:

• Add web form controls to a web form.

• Customize the appearance and layout of a web form.

• Create form rules that define the behavior of the controls on a web form.

Figure 10-1 shows an example of the web form designer.

Figure 10-1 Oracle Business Process Composer - Web Form Designer

Description of "Figure 10-1 Oracle Business Process Composer - Web Form Designer"

When you open a web form, the web form designer appears as a tabbed pane within Oracle Business Process Composer. The web forms designer is divided into the following areas:

• Web forms component palette

• Web form toolbar

• Forms canvas

• Properties editor

• Data sources

  Note:

  Data sources are available only in web forms created through the data first use case. See Walkthrough: Creating a Web Form Using the Data First Method for information about creating web forms based on a human task payload.

Each area of the web forms designer is described in the following sections.

10.2.1 Introduction to the Web Forms Component Palette

The component palette contains the controls you can add to a form to define how your users interact with your business application. The form palette appears on the left side of the web form editor as shown in Figure 10-1. You can add a form control to a web form by dragging the control from the palette to the form canvas.

See Introduction to Web Form Controls for a description of the web form controls that are available in Oracle BPM. See How to Add Controls to a Web Form for information dragging controls to a web form.

10.2.2 Introduction to the Web Form Editor Toolbar

The web form editor contains a toolbar that provides access to form-related features.

The web form editor toolbar contains the following buttons:

• Edit rules: Click to access the rules editor.

  This button toggles between Edit rules and Edit form.

• Edit form: Click to access the form editor.

  This button toggles between the form rules editor and the web form editor.

• Test web form: Opens the form in a browser window.

  In this window, you can view how the web form appears to end users. You can also test the behavior of form rules.

• Refresh: Refreshes the external data source (human task payload) of the form.

  If you make changes to the human task payload, you must refresh the data source of the web form. This button is only applicable to web forms created using the data first method. See Walkthrough: Creating a Web Form Using the Data First Method for more information.

• Localization: Opens the resource bundle editor.

  This editor allows you to localize components of the web form and web form controls. Only languages that have been added using the project's Language setting are available. To configure language support, select the target language in the editor and add translation strings for the form's elements.

• Business Objects: Opens the Form Business Objects dialog.

  Add business objects from the catalog to be available in your form. Once selected, business objects appear in the Data Sources part of the component palette. To use a business object in a form, drag it from the component palette to the form. See Adding Business Objects to a Web Form for more information.

10.2.3 Introduction to the Property Editor

Use the property editor to define the properties of a web form or web form control. When you click on a control in your form, the Properties area displays the control's properties so you can view and edit them.

The properties editor contains tabbed panes that display the properties of the web form or web form control grouped by function. Figure 10-2 shows an example of the properties editor.

Figure 10-2 Web Form Designer - Properties Editor

Description of "Figure 10-2 Web Form Designer - Properties Editor"

See How to Edit the Properties of a Web Form for procedures about editing a web form and web form control properties. See Web Form and Web Form Control Property Reference for information about each property.

10.2.4 Introduction to the Data Source Panel

The Data Source panel displays the list of data elements that can be incorporated into your form. See Introduction to Data Sources for more information.

From the data source panel, you can generate web form controls based on all the data elements in the payload or you can generate web form controls based on specific data elements. These can include business objects that you have previously selected from the catalog using the Form Business Objects dialog, accessed from the web form editor toolbar.

Note:

Data sources are only available in web forms created based on a human task payload. See Walkthrough: Creating a Web Form Using the Data First Method for information.

Figure 10-3 shows how the data source panel appears in a web form created based on a human task payload.

Figure 10-3 Data Source Panel

Description of "Figure 10-3 Data Source Panel"

See Introduction to Data Sources for more information about data sources in Oracle BPM. See Walkthrough: Creating a Web Form Using the Data First Method for information on creating a web form based on a human task payload.

See Adding Business Objects to a Web Form for information on loading business objects from a catalog, and placing them on a web form.

10.2.5 Introduction to the Form Canvas

The right side of the web form designer is the form canvas. You can create a web form by dragging controls from the component palette to the form designer canvas. Figure 10-4 shows an example of the form canvas containing several controls.

Figure 10-4 Form Canvas

Description of "Figure 10-4 Form Canvas"

10.3 Introduction to Web Form Controls

Web form controls are the user interface components that you add to a form to define the user interface of your business application. Web form controls are defined in HTML, but using the web form editor, you do not have to edit any of the underlying code.

Web form controls are described in the following sections. For information on the properties that you can configure for each web form control, see Web Form Control Properties.

10.3.1 Input Controls

Input controls allow users to enter data (text, dates, numbers, and so on) into a form. Input controls automatically prevent users from entering the wrong data types. For example, if a user enters letters into a number control, the form displays an error message. This validation happens automatically. The function of each input control is described below.

To validate the content in each input control, Oracle BPM assigns a default XML schema data type to each control. Table 10-1 shows the default data types for each input control.

Table 10-1 Input Controls - Default Data Types

Input Control	XML Schema Type
Text	xsd:string
Date	xsd:date
EMail	types:emailType, an xsd:string restriction pattern defined in types.xsd.
Money	types:number, an xsd:double restriction defined in types.xsd.
Phone	types:phoneType, an xsd:string restriction pattern defined in types.xsd.
Quantity	xsd:integer
Number	types:number, an xsd:double restriction defined in types.xsd.
Boolean	xsd:boolean

10.3.1.1 Text

The text control allows users to enter text and is primarily intended for short, one-line entries.

10.3.1.2 TextArea

The textarea control allows users to enter any text and is designed for longer, multi-line submissions. When a user enters data, a scroll bar appears, if necessary, to accommodate the text. The textarea control uses a property called # of Rows that controls the default number of lines visible in the input area.

In HTML there is no property for setting the maximum length on a textarea control. Therefore, this control does not have the maxlength property like the text control. If you must specify a maximum length, you should use the text control, or use a form rule to limit the amount of text a user can enter. See Working with Web Form Rules for more information.

10.3.1.3 Date, Time, Date/Time

The Date control allows users to enter information as a date, time or date plus time control. To use Date, Time and Date/Time controls, add a Date control to your form and use the Control Type property to choose from date, time or date/time. The control is configured accordingly.

10.3.1.3.1 The Date Control

Use the date control type to display the date input field with a calendar icon.

The default Date Format is Automatic. When Automatic is selected, both entry and display formatting of dates are locale specific. You still have the option to specify a particular date format that is independent of the locale by using the format field, but this is not recommended.

If a user clicks the calendar to choose the date, the date selected is displayed in the default mm-dd-yyyy format, for example 09-01-2014. Users can manually enter dates in any format, but they are then reformatted to mm-dd-yyyy.

Valid date formats use three different separators (. / -) and three date formats (dd/mm/yyyy, mm/dd/yyyy, and yyyy/mm/dd). The following examples show how dates can be specified:

• mm-dd-yyyy (07-26-1966)

• mm/dd/yyyy (07/26/1966)

• mm.dd.yyyy (07.26.1966)

• dd-mm-yyyy (26-07-1966)

• dd/mm/yyyy (26/07/1966)

• dd.mm.yyyy (26.07.1966)

• yyyy-mm-dd (1966-07-26)

• yyyy/mm/dd (1966/07/26)

• yyyy.mm.dd (1966.07.26)

The date is converted to the standard xsd:date format of yyyy-mm-dd in the submissions XML document using the following format:

<Order Date>2012-03-06</Order Date>

Dates are adjusted to be within 80 years before or 20 years after if the date is expressed with a two digit year. For example, using a pattern of "mm/dd/yy" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits, is interpreted literally. The dates "01/02/3" or "01/02/003" are parsed using the same pattern as Jan 2, 3 AD. Similarly, "01/02/-3" is parsed as Jan 2, 4 BC. Web forms will always format for 4 digit years.

10.3.1.3.2 The Time Control

Use the time control type to display only the time input field on your form. The Time Format property drop down menu appears, allowing a user to select between four variations of military and standard conventions. The Time Format control defaults to hh:mm using military time, for example 18:30. Other format options include standard time (AM/PM).

Changing the control type to Time does not display the date picker.

The default Time Format is Automatic. When Automatic is selected, both entry and display formatting of times are locale specific. You still have the option to specify a particular time format that is independent of the locale by using the format field, but this is not recommended.

In addition to Automatic, the Time Format control has four standard formats using both military and standard time. There are two separators, the dot and the colon. Examples are shown below:

• hh:mm (18:30)

• hh.mm (18.30)

• hh:mm - AM/PM (06:30 PM)

• hh.mm - AM/PM (06.30 PM)

• hh:mm:ss (18:30:15)

• hh.mm.ss (18.30.15)

• hh:mm:ss - AM/PM (06:30:15 PM)

• hh.mm.ss - AM/PM (06.30.15 PM)

The local time is converted to UTC format in the submissions XML document. Here is an example: <Order Time>15:42:00Z</Order Time>. The capital "Z" after the time is necessary for proper initialization.

10.3.1.3.3 The Date/Time Control

Use the Date/Time control to display two input fields: one for the date and another for the time.

The default Date/Time Format is Automatic. When Automatic is selected, both entry and display formatting of dates and times are locale specific. You still have the option to specify a particular date/time format that is independent of the locale by using the format field, but this is not recommended.

A property drop down menu allows you to select from nine valid formats for the date of the control and four choices in military and standard time for the time. See The Date Control and The Time Control for more information.

Default formats for date and time remain mm-dd-yyyy and hh:mm.

• When you enter a date in the date part (or select with the picker), it automatically completes the time portion of the control with a value for 12:00 AM.

  The value displayed depends on the time format selected:

  • 00:00 displays if the selected time format is hh:mm

  • 12:00 AM displays if the selected time format is hh:mm - AM/PM

  • 00:00:00 displays if the selected time format is hh:mm:ss

  • 12:00:00 AM displays if the selected time format is hh:mm:ss - AM/PM

• You cannot enter a time value without a date value.

• Changing the Control Type to Time does not display the date picker.

• The time input field cannot be labeled. You must ensure that the label for the date portion is descriptive enough to include the time portion.

  If date and time labels for the appropriate input fields are required, two separate controls must be used or the label for the date portion should be extended over the time input field.

The local time is converted to and saved in UTC format and the date is converted to the standard xsd:date format of yyyy-mm-dd In the submission XML document, for example:

<OrderDate>2012-01-01TO05:00:00Z</OrderDate>

The capital Z after the time is necessary for proper initialization.

Form rules can be applied to the Date/Time control in all variations. Form rules should execute in the form time zone.

10.3.1.4 Email

The Email form control allows users to enter a valid EMail address. The address must conform to the following syntax: <name>@<name>.<string>.

10.3.1.5 Money

Use the money form control to allow users to enter U.S. currency. Users can enter commas or decimal point. If a user does not enter them, the form displays these symbols automatically. For example if a user types 4000, the form will display the value as 4,000.00. The form also rounds all entries to two decimal places.

If a user types more than two digits after the decimal place the XML submissions document stores as many digits as the user entered but does not include the dollar symbol, decimal point, or commas.

10.3.1.6 Phone

The phone web form control allows users to enter a phone number using any of the following formats: xxx.xxx.xxxx, xxx-xxx-xxxx, xxx.xxxx, or xxx-xxxx. To enforce one of the 10-digit formats (to require an area code), edit the control's Pattern property.

10.3.1.7 Quantity

The quantity web form control allows users to enter quantities or any whole numbers (integers). The form displays an error message if users enter decimal points, commas, or anything other than an integer.

10.3.1.8 Number

The number web form control allows users to enter decimal numbers. Users may enter any number of digits after the decimal place.

10.3.2 Selection Controls

Selection controls allow users to select from a list of several options. Oracle BPM supports the following selection controls:

• Dropdown

• Radio

• check box

• True/False

Note:

The web form control palette does not include a combo box control which is a drop down list in which a user can type a new value or option. Combo boxes are not part of standard XHTML.

However, it is possible to use a combination of drop downs, radio buttons, or check boxes with an "other" option in combination with form rules. If a user selects "other," the rule then displays a text control (such as details or new entry that the user can enter.

10.3.2.1 Dropdown

The dropdown control adds a drop down list to a form. By default the first choice in the drop down list is blank. You must define the other choices by editing the control's Options properties.

10.3.2.2 Radio

The radio control adds mutually exclusive radio buttons. You must define the number of radio buttons and the specific choices by editing the control Options properties.

After selecting a radio option as the default, to change it, you must remove that option from the control and tab out of the options property so that it is removed from the control. You can then add the option back to the control's option list.

10.3.2.3 Check Box

The check box control adds a set of check boxes allowing the user to select one or more options. Like other selection controls, you edit the control's Options properties to define the number of check boxes and define the options available.

10.3.2.4 Booleancheckbox

The booleancheckbox control allows a user to select a true or false value in a control instead of entering data. The control options default to "true=Yes" and "false=No". You can change the option labels to other values if necessary. However, the option values cannot be changed and remain true or false.

Selecting the Yes check box sets the value to true in the XML document for the control data while leaving it deselected defines a false value. No value appears in the XML document.

10.3.3 Group Controls

Use group controls to organize your forms based on the types of information you require to present to your users.

10.3.3.1 Sections

Use the sections control to create groups of controls that users can expand and collapse.

In a web form, users can click the expand icon to expand and collapse sections. You can specify a default value to determine if the section is initially expanded or collapsed.

After dragging a section control into your form, you can drag any other controls inside it, including panels and other section controls. If you have a required control inside a collapsed section, the section label turns red to cue users that they must expand the section and supply the required information. If you delete a section control while designing a form, all controls within the section are also deleted.

10.3.3.2 Optional Sections

Optional sections can cause the validity of a form to change dynamically. For example, consider the following form:

Figure 10-5 Optional Section

Description of "Figure 10-5 Optional Section"

The only required field in the form is Name. The entire Address section is optional. However, if the user chooses to enter an address, then the entire address is required as indicated by the yellow background when the user tabs to the City field. If the user enters a value in the Street field, the City, State and Zip fields will become invalid until valid values are entered in the three newly required fields.

Figure 10-6 Optional Section With Incomplete Data

Description of "Figure 10-6 Optional Section With Incomplete Data"

If the user removes the value from the Street field, the form validity is automatically recalculated. The Address section is no longer invalid because it is optional. The generated XML instance document will also not contain an address element.

10.3.3.3 Tabs

You can use the tabs group control to create a tabbed view as shown in Figure 10-7.

Figure 10-7 Web Form Containing Multiple Tabs

Description of "Figure 10-7 Web Form Containing Multiple Tabs"

By default, when you drag the tab control into a form there are three individual tabs. To add or remove a tab, click the tab and then click the Add (+) or Delete (-) icon. Additional tabs are added to the right of the tab from which you clicked the add icon.

To rearrange the tab order, drag one tab on top of another tab. The tab you dragged moves to the right of the tab upon which it was dropped. You can drag in other controls, including other group controls, into any individual tabs. Users see only those controls in the currently selected tab.

To move a group of tabs to another area of a form, click the area to the right of the tab drag the entire group to the desired location.

10.3.3.4 Panels

The panels control creates columns within a web form. You can add multiple columns to a form by dragging in as many panels as necessary.

By default a panel's width is set to 49%. When you drag two panels into your form, the second panel is automatically aligned with the first panel. Panels have a 1px border to make their boundaries visible. Therefore, in a two-column layout you cannot make both widths 50%.

Since panels are group controls, you can drag other controls inside them. If you want to rearrange the order of your panels, you should remember that the drag-and-drop restriction that prevents you from dropping a control below a group control. If you have three columns and want the middle column at the far right, you must drag the middle column above whichever control is directly beneath the panel.

In a three or four column layout, to move one of the middle columns or the right-most column to the far left, you must drag and drop it above your left-most column.

Although panels have labels you can edit during design, the panel labels and panels themselves are not visible to users at runtime or when testing a form. Only the controls inside a panels are visible. These controls are organized visually according to the width of the panels.

If you delete a panel, any controls you've dragged inside it are automatically deleted.

10.3.3.5 Tables

Use the tables layout control to conserve space within a web form. This control allows you to arrange the form controls in a grid pattern.

You can edit the table name and column names. You can also drag and drop new controls from the palette, and set the widths of the columns. You can control the minimum and maximum number of rows in the table. The Add and Remove icons automatically appear to the left. You can also use form rules to calculate values, enable or disable fields, show or hide fields, and so on.

When you drag the table control into a form, by default, it has three rows and three columns. The columns contain the default names col 0, col 1 and col 2. All of the cells in the table are defined as required. The Add and Delete icons are displayed for each row in the table, allowing you to add and delete rows, depending on the Min/Max property values.

It is strongly recommended that column names in a table be unique.

Rearrange table columns by clicking on the arrow that appears when you click in the column heading of the column that you wish to move. Columns move to the right until the last column position in the table is reached.

Table controls have the following limitations:

• Table controls cannot be used in a repeat control.

• Table cell borders are not shown in print view.

• Table column names cannot be edited from the work area. Use the property editor.

10.3.3.6 Repeats

Repeating controls dynamically display multiple copies of a web form control. This is useful when you want to allow users to enter multiple information of the same type, for example, a phone number. A repeat control can dynamically display as many controls as required rather than having to explicitly add extra input controls. Repeat controls are used to repeat data elements and sections within a form.

You can add a repeat control to a web form, then drag and drop additional controls into the repeat control in the same way that you add controls to a tab, panel, or section. You can surround an individual control with a repeat control, or it can include an entire section control. This section control should contain all of the web form controls that must be repeated.

After adding a control to a repeat control, you can select the control to view and edit its properties. Web form controls added to a repeat control contain two additional properties:

• Min#: Specifies the minimum number of times the control can be repeated.

  The default value for Min# is 0

• Max#: Specifies the maximum number of times the control can be repeated.

  The default value of Max# is 1.

You must edit this value to define how many times the control is repeated. If you do not edit the value, the control does not repeat.

These properties define how the control appears to end users. When the value of these properties is greater than one, the user sees an add icon that automatically creates another control. In the form editor, clicking on the control automatically increments the property.

The Min# value defines the minimum number of controls that must be added and filled-in by the end user.

If a user adds controls beyond the number defined by Min#, they must fill in the data for the first controls up to the value of Min#. For example, if Min# is defined as 3 and the user adds 5 controls, the first 3 controls, in order starting from the top of the form, must contain data. If a user adds controls up to the number defined by Max#, the add icon is no longer displayed.

To explain to users how to add additional data elements, you can provide a message using a message control The following example shows one way of doing this:

<center>Click on the <img src="/frevvo/images/icons/add.gif"/> icon to addmore phone numbers to the list.<br/></center>

When you edit the label or any properties of a control inside a repeat control, your changes are applied to every instance of the control inside the repeat control. If you delete a control inside the repeat control, all instances of the control are deleted.

Like panel controls, repeat controls are hidden when testing or using forms. Only the controls within the repeat control are visible.

There are some key differences between repeat controls and the other grouping controls:

• You cannot add button, message, or image controls.

• You cannot drag in message, image, link, tab, or table controls.

• A repeat control can contain only one web form control.

  You cannot add tab controls, panels, or other repeat controls. To add multiple controls to a repeat control, you can add multiple controls to a section control, then add the section to a repeat control.

  If you must add more controls to the section, you must drag the section out of the repeat control, add the additional controls, then drag the section control back into the repeat control. However, you can add a section control to a panel control without having to remove the section out of the repeat control.

When adding a repeat data element that is part of a data source, Oracle Business Process Composer automatically generates a repeating item in the control The schema of the repeat control automatically enforces the minimum and maximum requirements.

10.3.3.7 Changing a Repeat Control to a Table

You can change a repeat control to a table control through the Control Type or Display As properties, depending on whether the repeat was dragged and dropped from the palette or added from schema. Refer to this documentation for the details.

When you change a repeat to a table or vice versa and there are referencing rules, it is recommended that you check the rules for the correct syntax and section names.

10.3.4 Other Controls

In addition to input, selection, and group controls, Oracle BPM provides other web form controls to define how users interact with a web form.

10.3.4.1 Message Control

Use the message control to add static text on your form. You must provide the text in the control's Message property. You can include XHMTL with your text. For example you may want two lines with different font sizes or colors.

The browser formats the XHMTL when users access the form. For example, if you want to create a header in a web form, you can use a combination of panels and message controls as shown below.

<center style="font-weight:bold;"> 
Connecticut Surgeons, LLC 
</center> 
<center style="line-height:1.2em;"> 
82 Anderson Road<br/> 
Branford, CT 06180<br/> 
</center>

You can choose a message type to display different pre-defined background colors, decorators or a border from the Message Type dropdown on the Setting tab of the property panel. These settings can override the values you have specified for BG Color and Label Color. For these values to take effect, select None for the Message Type.

Message Type values include:

• Default

• None

• Bordered

• Success

• Info

• Warning

• Error

10.3.4.2 Link Control

Use the Link Control to include a URL in your form. When a user clicks the link, the target URL opens in a separate browser window.

10.3.4.3 Button Control

Use the button control to add a button to your form. This control is primarily used in conjunction with form rules.

Note:

The button control does not work in repeating items.

10.3.4.4 Image Control

Use the image control to include an image (picture, logo, and so on) in your form. The image control allows you to add JPG, GIF, and PNG files or any other image type that your browser supports.

When you drag in the image control, a Browse button and an Upload Image button appear. Click Browse, navigate to the image you want, and click Upload Image. After uploading the image, the Browse and Upload Image buttons are no longer available. To change the image you must delete the image control and drag in a new one.

Before uploading images, you must ensure that they are sized to fit within a form. The standard form size is 600 pixels. You can resize an uploaded image by selecting the image control in the designer, clicking on the style tab in the properties panel, and setting the width.

Units are px, % or em. You must include the units. For example, specifying a value of 50% resizes the image to half the width of the form or panel.

10.3.4.5 Trigger Control

The trigger control adds a button to your form and is used in conjunction with rules. See Using Dynamic Content in Form Rules.

Caution:

Triggers do not work in repeating items.

You can change the color of the Trigger button on the Setting tab of the properties panel. You cannot center the text on a Trigger or remove the decorator. The New Line property is checked by default. The Button Color can be changed by selecting one of the choices in the Button Color dropdown on the Style tab.

10.4 Introduction to Data Sources

Data sources allow you to create web form controls based on existing data structures. In Oracle BPM these data structures are defined by a Human Task payload.

After creating a human task payload, you can create a new web form based on the payload data. See Walkthrough: Creating a Web Form Using the Data First Method for information about creating a web form based on payload data.

10.4.1 Web Form Controls Generated by Payload Data Types

Table 10-2 shows the type of web form control generated for each data type supported by human task payloads.

Table 10-2 Human Task Data Types and Their Corresponding Web Form Control

Data type	Web form control
String	Text control
Binary	Text control
Boolean	Booleancheckbox. If checked, the value is set to true and if unchecked it is set to false if the element is required. No value is specified if the control is optional. You can set the label of the true and false options through the Labels property. However only the first option, which maps to the true choice is displayed. If you add more then two labels the extra labels are automatically removed.
Int / Int64	Text control
Real / Decimal	Text control
Interval	Text control
Time	Date control
Components	Section Human task payload data created based on a business object is added to a section form control. Individual data elements within the component generate the same form controls as other data types. These are added to the section control. After adding them to a form, you can rearrange them as necessary.

Most of the controls generated from a human task payload are created as text controls. However, all validation for the controls are based on the original data type datatype. For example an xsd:integer type only allows numeric values.

Schema elements that specify element restrictions are generated as selection controls. The control is created as a dropdown if there are four or more valid choices and a radio button if there are fewer than four valid values. You can change the display type between radio, dropdown, and check box using the Display As property.

10.4.2 Modifying Web Form Controls Generated From Data Elements

After generating web form controls from data elements you can:

• Update the data payload of the human task and recreate the web form.

• Edit the controls in the web forms editor.

10.4.2.1 What You Can Edit Using the Web Form Editor

You can perform the following on a web form control after generating it from a data element:

• Edit the web form control's name.

  You can edit the name that is displayed in the web form editor. However, the underlying XSD is not changed.

• Create or edit web form rules used by the web form control.

• Set default values for the web form control.

• Edit the layout of the web form controls within the web form.

  You can move controls in sections or panels as required. However, you cannot add or remove a generated web form control from a repeat control.

• Edit the Display As property of the web form control.

  See Introduction to the Display As Property for more information.

• Edit the web form control's label.

10.4.2.2 What You Cannot Edit Using the Web Form Designer

The following changes cannot be made when generating web form controls based on data elements:

• Make edits to web form controls that alter how the web form or web form controls are validated.

• Alter the number of repeats of a repeating control.

• Add additional web form controls that require changes to the underlying data source.

10.4.3 Introduction to the Display As Property

The Display As property is only supported by web form controls generated from a data source. Use the Display As property to change the way your control appears on a web form. For example, a text control can be changed to a dropdown control or vice versa. This changes the control's appearance on the form, but does not change how the control validates data. To modify how the control is validated, you must redefine the human task payload data and recreate the web form.

To see the control's underlying data type and the global element to which it is bound, hover over the property tab. The expanded Data Source displays the XSD path as a tool tip.

If you set the Display As property to a select web form control (radio, dropdown, or check box), the Label property is enabled. By adding strings into the labels property you can restrict the values allowed to be entered into this control when users use your form. When the form is submitted the value is equivalent to the selected option label.

Another way to set the labels is through a rule to dynamically initialize the options when the form loads. See Working with Web Form Rules for more information.

The Display As property is not available for the following controls when based on a data type:

• Message

• Repeat

• Date, Time, or Date/Time

• Boolean

10.5 Walkthrough: Creating a Web Form Using the Form First Method

You can use Oracle Business Process Composer to create a web form that is not based on pre-existing data.

See Introduction to Web Forms for information about the use cases for creating web forms.

To use the form first use case, you create a web form directly from the Project Home Page. After creating the web form, you use the web form designer to rearrange the form controls as required.

To create and edit a web form with no previously defined data:

1. Create a new web form using the Project Welcome Page.

   1. Ensure that you are editing the project.

   2. From the Project Welcome Page, select Web Forms.

   3. Click the New Web Form icon, then enter a name.

   4. Click Create.

2. Add controls to a web form.

   After creating a new web form, you can add form controls as necessary to define how users interact with your application. See How to Add Controls to a Web Form for more information.

3. Edit the web form and web form control properties.

   You can edit the properties of your web form and its controls to determine their behavior and appearance. See How to Edit the Properties of a Web Form for more information.

4. Add form rules to a web form.

   You can add form rules to your web form to further customize and control its behavior. See Working with Form Rules for more information.

5. Test your web form.

   You can use the web form designer to preview how your web form appears to end users. See How to Test a Web Form for more information.

6. Save your web form.

   To save a web form, you must save the entire project. See Managing Project Changes for more information.

7. Assign your web form to a human task.

   After completing your web form, you can assign it to a human task using the human task editor. When you assign the web form to a human task, the human task editor automatically generates the payload information based on the controls you added to the web form. If the human task already has an existing payload defined, it is replaced by a new payload defined by the web form.

   See How to Specify the Presentation of a Human Task for information about assigning a web form to a human task.

10.6 Walkthrough: Creating a Web Form Using the Data First Method

You can use Oracle Business Process Composer to create a new web form based on an existing human task payload.

See Introduction to Web Forms for information about the use cases for creating web forms.

Human task payloads are created using the human task editor. When creating web forms based on a payload, the payload becomes read-only. The following conditions apply:

• You cannot update the payload signature after you create the web form.

  In other words you cannot add or remove data objects nor change their type. However, if you have defined complex data types in the human task payload, you can modify them by editing the underlying business object.

• After creating a web form based on a human task payload, you cannot add web form controls to a form that require underlying data structures.

  Any additional data required by adding web form controls to the web form using the form editor is not be added to the underlying schema and is not available in the human task payload.

If you have not created the human task payload based on complex data objects, to modify the payload you must disassociate the human task from the web form, make the modifications to the payload, and create a new web form based on this new payload.

To create and edit a new web form based on an existing payload:

1. Create a new human task and define its payload.

   1. Create a new human task.

      See How to Create New Human Task for more information.

   2. Create the payload you want to use as the base for the new web form.

      See How to Create and Configure the Data Payload for a Human Task for more information.

   3. Open the human task.

      See How to Open a Human Task for more information.

   4. Select the Basic tab.

   5. In the Presentation area, select Web Form, then click the Add icon.

   6. Enter the name of the web form, then select Based on payload.

   7. Click Create.

      The web form is created and assigned to the current human task.

   8. Click Edit to edit the web form.

   The web form editor displays a blank form.

2. Generate web form controls from payload data.

   After creating a web form based on a payload, you can use the payload data to generate the corresponding web form controls. The payload data appears in the Data Structures pane on the left side of the web form editor.

   See How to Add Controls Based on Data Sources for more information.

3. Add additional web form controls.

   You can add additional form controls as necessary to define how users interact with your application. See How to Add Controls to a Web Form for more information.

   Note:

   You can add additional controls to refine the look and feel of your web form. However, any data controls that you add are not reflected in the underlying payload.

4. Edit web form and web form control properties.

   You can edit the properties of your web form and its controls to determine their behavior and appearance. See How to Edit the Properties of a Web Form for more information.

5. Add form rules to a web form.

   You can add form rules to your web form to further customize and control its behavior. See Working with Form Rules for more information.

6. Test your web form.

   As you are designing a web form, you can test its appearance and the behavior of form rule. See How to Test a Web Form for more information.

7. Save your web form.

   To save a web form, you must save the entire project. See Managing Project Changes for more information.

10.7 Working with Web Forms

After creating a new web form, you can use the web form editor to add web form controls, edit form control properties, and test the web form.

The following sections describe how to add various types of controls to the form.

10.7.1 How to Add Controls to a Web Form

You can add controls to a web form by dragging and dropping from the web form control palette to the web form canvas. You can drag/drop above, below, to the left and right of most controls. If you are not dragging your control over a group control, your control will be placed at the top of your form.

As you drag a control, the position cursor changes to indicate its status.

Table 10-3 Web Form Position Cursor Icons

Position Cursor Icons	Description
Do Not Drop	The control you are dragging can’t be dropped over the area.
Drop	Your cursor is over an area on the canvas where dropping a control is allowed.
Drop over	Your control will be placed above the control over which you are hovering. You’ll see this icon when you drag the control over the top half of an area into which the control can be dropped.
Drop under	Your control will be placed below the control over which you are hovering. You’ll see this icon when you drag the control over the bottom half of an area into which the control can be dropped.
Drop right	Your control will be placed to the right of the control over which you are hovering. You'll see this icon when you drag the control over the right half of another control.
Drop under	Your control will be placed will be placed to the left of the control over which you are hovering. You'll see this icon when you drag the control over the left half of another control.

Other important drag-and-drop rules:

• If you let go of a control while the Do Not Drop icon is showing, your control goes back to where it was - either back to the Palette or where it was in your form before you tried to move it.

• You can drag and drop above, below, to the left and right of most controls.

• You can drop controls above and below the Section, Tab, Table, Repeat and Panel.group controls.

• Panels can be dropped to the left or right of other panels, however, you cannot drop other controls in a similar manner to the left/right of panels.

• You can never drop two different controls into a repeat control—for example, you cannot drag in a quantity control if your repeat control already contains an EMail control.

  If you require multiple controls inside a repeat control, first drag the controls into a section, then drop the section into the repeat. After the section is inside your repeat you may not add anything else to the section, so build the section first in this case. You also may never drop a panel, tab or another repeat control inside a repeat control.

To add controls from the component palette:

1. Open the web form where you want to add controls.
2. In the component palette click the control you want to add, then drag it to the form canvas.

   As you begin to drag a control from the component palette, the position cursor changes depending on its position in the form canvas.

3. Release the mouse button to add the new control.

10.7.2 Creating Multi-Column Forms

You can create forms with multiple columns.

All control widths are specified in columns. The width is selected by clicking on a grid in the style tab.

When dropping controls from the palette on an empty canvas or above or below an existing control, the newly dropped control is 12 columns wide.

If you drag a control from the palette and drop it to the left or right of a control, the newly dropped control will take the width of the control you dropped on. The width of a control that is already in your form must be adjusted manually by the designer if the position of the control is changed.

To create a multi-column form:

Drag and drop panels from the palette and then drop additional controls inside of the panels. Panels can be dropped to the left or right of other panels. A newly dropped panel dropped to the left/right of another panel will take the width of the panel it was dropped on.

Alternatively, drag and drop the first control onto the canvas, modify the width to your specification and then drag and drop additional controls to the right of the previously dropped one. The controls will "wrap around" and line up in columns.

10.7.3 How to Add Controls Based on Data Sources

After creating a web form based on the payload data of a human task, you can automatically generate web form controls for the data elements defined in the payload. You can generate form controls from all of the data elements or individual data elements.

See Walkthrough: Creating a Web Form Using the Data First Method for more information.

10.7.3.1 Generating Form Controls for all Data Elements in a Payload

To generate form controls for all the data elements in a payload:

1. Open the web form you created based on a human task payload.
2. In the Data Sources pane, click the Add (+) icon to the right of the HumanTaskPayload node in the data elements tree as shown in Figure 10-3.

   Oracle Business Process Composer generates a web form control for each of the data elements in the payload. The controls are added to the web form above the currently selected control. See Introduction to Data Sources for information about which web form control is generated for each data type of the payload.

3. Edit the layout of the controls as necessary by dragging and dropping them within the web form.

   Note:

   You cannot add a control generated from a data element into a repeat control.

10.7.3.2 Generating Form Controls for Individual Data Elements

To generate form controls for individual data elements in a payload

1. Open the web form you created based on a human task payload.
2. In the Data Sources pane, click the bullet to the left of the HumanTaskPayload node as shown in Figure 10-3.

   Oracle Business Process Composer displays a tree showing a list of the data elements within the payload.

3. For each of the data elements that you want to add to your form, select the Add (+) icon to the left of the data element.

   Oracle Business Process Composer generates a form control for the data element. When adding data elements individually, the form controls are added directly at the beginning of the form. They are not added to a form panel.

4. Edit the layout of the controls as necessary by dragging and dropping them within the web form.

   Note:

   You cannot add a control generated from a data element into a repeat control.

10.7.4 Adding Business Objects to a Web Form

Add business objects to a form from the Data Sources panel. The Data Sources panel includes business objects that you have added from the catalog using the Form Business Objects dialog, accessed from the web form editor toolbar.

To add business objects to a web form:

1. Edit your web form and click the Business Objects control on the web form editor toolbar.
   Description of the illustration GUID-F34F7858-9C46-45F0-B615-EBC3ABEB3F91-default.png
   The Forms Business Objects dialog displays.
2. Select the business objects to include as data sources by using the controls on the dialog to move them to the Selected panel.
   Description of the illustration GUID-3E4A0191-B2F6-4A69-B237-C81C7314A17C-default.png
3. Click OK to close the Forms Business Objects dialog.
4. Drag business objects from the Data Sources panel of the palette to your form.
   Description of the illustration GUID-C618C51E-C7E0-4FEC-AAA9-AE83AEA1DC6E-default.png

10.7.5 How to Show Which Web Controls Were Created from a Data Source

The web forms editor allows you to view which web form controls were automatically generated from a data source.

To show which web controls were created from a data source:

1. Open your web form.
2. Expand the Data Sources panel.
3. Click the Show Form Controls icon.

   Each generated web form control is highlighted in the web form canvas.

10.7.6 How to Edit the Properties of a Web Form

You can edit the properties of a web form to configure general settings and style for the web form.

To edit the properties of a web form:

You can edit the properties of a web form to configure settings for the form as well as general style properties. See Web Form Properties for information on the properties supported by Oracle BPM.

1. Open the web form whose properties you want to edit.
2. Click the web form header at the top of the form canvas.

   The properties tabs for the web form appear in the properties editor.

3. Edit the properties for the web form in the properties editor.

10.7.7 How to Edit the Properties of Web Form Controls

You can edit the properties of a web form control to configure how the control appears in your web form.

To edit the properties of a web form control:

You can edit the properties of individual form controls to configure its behavior and style. See Web Form Control Properties for information on the properties available for each form control.

1. Open the web form containing the control you want to edit.
2. In the form canvas, select the control.

   When you select a control in the form canvas, it is highlighted.

3. In the properties editor select either the Settings or Style tab, then edit the properties as necessary.

   See Web Form Control Properties for a description of each supported web form control property.

10.7.8 How to Delete a Web Form

You can delete a web form your BPM project from the Project Home Page.

Note:

You cannot delete a web form that is associated with a human task. If you want to delete a web form associated with a human task, you must first disassociate it using the human task editor.

To delete a web form:

1. Go to the Project Home Page.
2. Select Web Forms, then position the cursor over the web form you want to delete.
3. Click the Delete icon, then click OK to confirm that you want to delete the web form.
4. Save your project.

10.7.9 How to Remove a Control from a Web Form

You can remove form controls from a web form using the web forms designer.

Note:

After deleting a control it cannot be undone. You must add a new control to the web form and configure its properties.

10.7.9.1 Removing Controls

To remove a control from a web form or organizational control:

1. Open the web form whose control you want to delete.
2. Click on the control to select it.

   When you select a control, it is highlighted.

   Note:

   Ensure that you select the individual control you want to delete and not the organizational control.

3. Click the Click to remove button.

10.7.9.2 Removing Organizational Controls from a Web Form

To remove an organizational control from a web form:

1. Open the web form containing the organizational control you want to delete.
2. Click on the organizational control you want to delete.

   When you select an organizational control, the control and all of the controls it contains are selected.

3. Click the Delete button.

   Note:

   When you delete an organizational control, all the controls it contains are also deleted.

10.7.10 How to Test a Web Form

While designing a web form, you can test its behavior directly in the web form editor.

Each time you supply a value in a control, the form sends an asynchronous request to the server to validate the data. You do not have to complete the entire form before discovering data was entered incorrectly—try to type letters in a number control, for example, and you'll immediately see an error message. If your form includes rules that are associated with a particular control, the server applies these rules as soon as users enter data in the control.

For example, perhaps your form has a rule that enables the Guest Name control when you select the Yes radio button in the Are You Bringing a Guest?. In this case the Guest Name control is enabled immediately--while you are still completing the form.

To test a web form:

1. Open your web form.
2. Click the Test Form button in the web form editor toolbar.
3. Test your web form by entering a date, selecting items from dropdown controls, and so on.
4. Click the Close (x) button when you are done testing.

10.7.11 About Localization in Web Forms

Web Forms can be localized to support multiple additional languages.

In order for a language to be supported, it must be added at the project level first. See Introduction to the Project Information Panel.

After a language has been added at the project level, translation strings for web form elements can be added in the web form editor. See Introduction to the Property Editor.