Administration Guide

Action Forms

On this page

An action's Form: list names the form the action shows. On Create Actions the list offers the object's own full form; on other actions, an action with no form set shows no form. A form you design is either shared or custom. A shared form can be reused by other actions of the class and is kept when an action that uses it is deleted. A custom form belongs privately to one action and is deleted with it, and you cannot point a second action at another action's custom form.

In the Settings App

Find a class's forms

In the workflow tree, each object class has a Components node, and its Forms leaf lists the class's shared action forms. A form made custom with Make Custom, a View Form, and a Web Portal form do not appear in this list. For each form, the list shows its name, description, caption, instruction, and window style, how many workflow items use it, and how many fields and attachment areas it has.

The list's toolbar offers New, Edit, Delete, and Copy Item, with a quick filter below the toolbar. Forms have no authored order, so there is no ordering command.

  • New opens the editor on a new form, and the list stays usable behind it.
  • Edit switches to the editor already open on that form, if there is one.
  • Copy Item saves a copy of the form and opens the copy in the editor.

A new form is named from the class, the form kind, and a five-digit counter, for example IncidentActionForm00001. The editor's window caption shows the form's name in square brackets, prefixed with an asterisk while there are unsaved changes.

Attach, detach, or reuse a form on an action

An action's Form tab holds a Form definition group with the Form: list, the form's caption and instruction, the Window Style choice, and two buttons, Make Custom and Reuse. While the list stands on the full form, Make Custom reads Use Custom.

Make Custom detaches the form as a custom form of this action.

To save the current form definition as a new shared form of the class:

  1. Click Reuse.
  2. In the Reuse Form prompt, enter a Form Name: of up to 50 characters. If a form of the class already has that name, the prompt shows "Another form with this name already exists. Enter a different name." and asks again.

The new shared form carries the current caption, instruction, and window style.

When you switch away from a custom form, the Settings App first asks "The Custom Form definition will be lost. Do you really want to change the current form?". A custom form built on the full form cannot be saved empty.

Set the form's general properties

The form editor has three tabs: General, Validation, and Usage. The Validation and Usage tabs show counters.

  • General shows the object class (read-only), Name: (mandatory, and unique among the class's forms), Description, Form Caption:, Instruction:, and Window Style:.
  • Usage lists every item, or every function, that references the form. Opening a row opens that item's own editor.

A form with no fields cannot be saved: saving is refused with an error, and the General tab gets the focus. A form set to Wizard cannot be saved while a recurrent Create Action uses it, that is, a Create Action available for Regular and Recurrent Tickets or for Recurrent Tickets only: saving is refused with a message, and the General tab gets the focus.

Add and arrange elements

The New menu of the fields list offers Field, Text, Attachment Area, AI Control, and Section (Page on a Wizard form).

  • Edit opens the selected row; Enter or a double-click does the same.
  • Delete removes the selected row after you confirm.
  • Move Up and Move Down move the selected row.
  • Copy and Paste are available on a Section or Text row only; the copy is added under the selected row as a new element.

Add a field

  1. In the form's fields list, choose New > Field.
  2. In Form Field, choose an Object Field or define a Virtual Field, then set its display properties and options as described below.
  3. Click OK.

The Form Field dialog offers two choices:

  • Object Field - one of the class's own fields.
  • Virtual Field - a field with its own name and type. The name must be unique among the form's virtual fields. The types are Integer, Logical, Currency, String, Memo, Encrypted, Date, Date/Time, Duration, Float, Reference, Lookup, Multi-select, and HTML. A virtual field has no length or precision setting of its own.

For an Object Field, Read Only is pre-checked and unavailable when the field is read-only, and Mandatory is pre-checked and unavailable when the field is mandatory or not editable. Mandatory is unavailable for a boolean field, object or virtual. For a Reference virtual field, OK stays unavailable until you choose a lookup object. On a form for the Self Service Portal, OK is refused with an error when the chosen field is not available to the portal.

The dialog's Display group holds:

  • Label: - optional. When it is blank, the field is captioned by its own name: the field's caption (prefixed Activity. for an activity field) or the virtual field's name.
  • Value: - with an F(x) button that opens the expression builder.
  • Filter: - with its own F(x) button. It is read-only unless the field is an Object Field on a lookup column that is not itself read-only, or a Reference virtual field with a lookup object chosen, and it is read-only on a form opened read-only. The filter is stored with the field, so it applies wherever that field is shown, not only on the form where you wrote it.
  • Hint: - with an ellipsis button that opens an editor titled Hint. Canceling that editor discards your changes without asking.

The Options group holds Mandatory and Read Only. For a Lookup or Multi-select field, Lookup values: sets the values, and OK is refused with "Please complete the lookup definition." while the field has none.

In the editors of the action that shows the form, the form's virtual fields appear in the Select Placeholder window under the category Form Fields, and choosing one inserts a placeholder with the VIR prefix (see Macros Reference). A Reference virtual field lists the referenced object's fields in SubItem:, and choosing one inserts a placeholder that joins the two names with a dot, for example %[VIR Assignee.Primary_Email]% for a Reference field Assignee over Persons.

Add a Text element

New > Text opens a window titled Text with:

  • A Text box and an Insert Placeholder... button.
  • A URL: box, whose ellipsis button inserts a placeholder into the URL.
  • SSP Localization Key: - up to 50 characters, digits and upper-case letters only; what you type is converted as you type. A new element gets a key that the form does not already use.

For the placeholders these buttons insert, see Macros Reference.

Add an attachment area

New > Attachment Area opens the Attachment Area dialog with the name pre-filled Attachments, or Attachments1, Attachments2, and so on when the form already has an area of that name, so a form can hold several areas. On a Self Service Portal form, the new area is added at the end of the list instead of under the selected row.

The dialog holds:

  • A name, unique among the form's areas.
  • Automatically attach files to the object - checked by default. When it is cleared, the area's files go to the item's program instead of becoming ordinary attachments of the object.
  • Label: - the area's caption.
  • Allow to attach: with Files and Existing attachments - both checked by default.
  • Mandatory under Options:.

Other parts of the configuration refer to the area by its name: the Add Attachments operation offers the form's areas as its source (acting on the action's own object, only the areas whose Automatically attach files to the object box is cleared), the Assign Parameter window lists them as values of an Attachment-type parameter, and they are available to conditions and text templates among the form's values.

Add a section or page

New > Section (New > Page on a Wizard form) inserts a separator row under the selected row. A separator owns every element below it down to the next separator. Moving or deleting a separator moves or deletes only the separator, and the elements between it and the next separator change owner.

The same dialog edits a section and a page. Its caption can be up to 100 characters. A blank caption is shown in the fields list in bold as <unnamed section>. A section or page can carry an optional visibility condition, shown as read-only generated SQL with an Edit... button that opens the criteria dialog.

Choose dialog box or wizard style

Window Style: offers Dialog box and Wizard. Switching it relabels New > Section as New > Page (and back) and regroups the form's validation rules, per page or as one flat list. On a Wizard form, the elements above the first page separator belong to an implicit first page named General, which appears as <General> when you scope a validation rule.

Add validation rules

The Validation Rules list opens from the editor's Validation tab or from the fields toolbar's Validation button, which reads Validation (N) and is highlighted while the form has rules. The list shows each rule's condition and text, and its order is the order of the rules. It offers New (Ins), Edit (Enter or a double-click), Delete (Del, after you confirm), and Move Up / Move Down (Ctrl+Up / Ctrl+Down).

On a Dialog box form the list is flat. On a Wizard form, rules are grouped under their pages plus a Form Level Validations group. Dragging a rule onto another page's group rescopes it, and Move Up / Move Down can move a rule into the neighboring page's group. Deleting a page does not delete its rules; they move to the form-level group.

The rule's window is titled Validation and holds:

  • A Condition group with the read-only generated SQL and an Edit... button.
  • A Message group with Text: (mandatory), an Insert Placeholder... button, and Type: - Error, Confirmation, or Information. The message is checked as a text template before it is saved.
  • On a Wizard form only, Form Level Validation or Page: with a list of the form's pages.

Save or close the editor

OK saves the form only if it has changed, then closes the window; Cancel closes it without saving. Esc does the same as Cancel, except in a list's filter row, which takes Esc itself. The toolbar's Save saves without closing and is available only while there are unsaved changes. When you cannot edit the form, the window offers Close instead of OK and Cancel.

View forms

A View Form opens in the same editor reduced to its General tab and titled View Form. The editor hides Form Caption:, Instruction:, and Window Style:, and the fields list hides the Mandatory and Read Only columns and offers no Attachment Area or AI Control. The field dialog has no Filter:, Hint:, or Options group. Every form added to the View Forms list is a View Form. The Web Forms page of the Web Portal section opens the class's default Web App view form in this editor.

When the form runs

These rules apply when an action shows its form.

  • Field limits. In the Web App, each field type enforces its own limits:
    • Integer: whole numbers from -2,147,483,648 to 2,147,483,647.
    • Float: at most 15 digits in total and 9 after the decimal point. A virtual Float field is displayed with two decimals.
    • Date and Date/Time: the picker goes up to 100 years from today. A typed date earlier than January 1, 1900 or later than that limit is replaced by the current date.
    • Duration: up to 99,999 hours and 59 minutes.
    • Currency: displayed with the number of decimals set by the Application Server's regional currency setting.
    • String and Encrypted: a virtual field has no maximum length; an object String or Encrypted field is limited by its own column. A Memo field has no maximum length in the browser.
  • Text elements. In the Web App, a Text element is shown as a paragraph that keeps its line breaks and does not render markup. When it has a URL, it is shown as an underlined link that opens in a new tab and goes to the URL exactly as entered.
  • Dialog box forms. When a Dialog box form opens, the starting values of its fields are calculated and the condition of each section is checked, so the form shows every section whose condition holds, all at once. A wizard instead checks a later page's condition and calculates that page's fields when Next reaches the page.
  • Wizard pages. Next goes to the first later page that has at least one element and whose condition holds for the values entered so far, and calculates that page's fields when you arrive on it. A skipped page's fields are reset to the values the form opened with, or cleared where there were none, so a skipped page contributes nothing to the object. When no later page qualifies, the wizard goes to its finishing step. When the form begins with a separator, the wizard opens on that first page. Back returns through the pages actually shown, so a skipped page stays skipped; on the first page shown, Back redisplays it. The form's caption and instruction are repeated on every page.
  • Validation. A rule's message is shown when the rule's condition holds for the values entered, with its placeholders filled in as a text template. Leaving a wizard page runs the rules scoped to that page; on the last page, or on a form with no pages, the form-level rules run as well. On the attachments step, on the final submission, and on a Dialog box form, only the form-level rules run. In the Web App, the messages are shown one at a time:
    • Error - shows OK and Help, and the action does not run.
    • Confirmation - asks Yes or No. Yes goes on to the next message and, after the last one, runs the action; No returns you to the form and runs nothing.
    • Information - shows OK and continues.
  • Actions - the actions whose Form tab attaches, detaches, or reuses a form.