Form set

From RPM Wiki

Table of contents
1 Summary
2 Details

2.1 Start a set (master form)
2.2 Add a form to a set (set form)
2.3 Copy
2.4 Delete
2.5 Import
2.6 Template and Fields

2.6.1 Common
2.6.2 Display
2.6.3 Edit
2.6.4 Field groups
2.6.5 Setup
2.6.6 Synchronization
2.6.7 XML

2.7 Status

2.7.1 Status triggers

2.8 Notes
2.9 Files
2.10 History
2.11 Participants

2.11.1 Owner

2.12 Actions

2.12.1 Global actions

2.13 Views, Download
2.14 Reconciliation
2.15 Archived
2.16 Process summary, Labels

3 Future
4 Misc.
5 Security
6 History
[edit]

Summary

Some business processes call for forms that have repeating groups of fields. Form sets address this by having multiple forms that are shown as if they were one. Some fields are common (not repeating), and others are unique (repeating).

  • This functionality is presented in the UI as "repeating fields"

What's happening behind the scenes is that a form created by the "Start a form" wizard begins a new set. This is the "master" form of the set. All other forms add only their unique fields (the fields that aren't common) and appear to use the remaining data like notes and files (see below) of the master form. These other forms in the set are called the "set forms". You only add forms to and remove forms from a set from the master form details page.

  • The terms master form and set form are used internally only.

The following information is appeared to be shared by forms in the set (by using the values from the master form):

  • Common fields
  • Status
  • Owner
  • Participant
  • Notes
  • Archived flag
  • Actions
  • Number and title field
  • Field setup

The general idea is to completely hide the details of form sets from the user. To them, it should appear that each set is just a form with repeating fields.

[edit]

Details

Essentially we are displaying the master form as normal then adding the unique fields from the set forms. If a user tries to bring up any form in the set, it's always the master form that's shown.

[edit]

Start a set (master form)

  • Start a form always starts a new set. No changes to this.
  • The new form uses the field setup of the template.
[edit]

Add a form to a set (set form)

  • On the details page of the master form is a link to add another form to the set.
  • "Required to start" is ignored, the user is sent straight to the edit page for the unique fields of this form.
  • There is no merging of sets or moving a form from one set to another.
  • The new form uses the field setup of the master form of the set, not the template.
  • User must be a participant, and
    • Staff user requires edit access to the form
    • Agent user requires permission to start forms in this process
[edit]

Copy

  • Creates a new master form and thus a new set.
  • Works as is as per the master form. Set forms are ignored and not copied.
[edit]

Delete

  • Deleting the master form using the link in the top toolbar will delete all the forms in the set.
  • Deleting set forms is done by a delete link displayed above their unique fields.
  • This works similar to the hierarchy of agents (the master form) and reps (set forms):
    • If the master form is deleted then only the master form of the set is shown in the recycle bin.
    • Otherwise the other forms, if deleted on their own, are available in the bin to be returned to the set.
    • If some forms from a set are deleted, then the set is deleted, then the set is restored, those first deleted forms in the set are still in the bin.
  • Agent users can not delete set forms
[edit]

Import

  • New "Form set" column to indicate if this is a new set form or an update
  • See Import forms (spec)
[edit]

Template and Fields

[edit]

Common

  • Common fields are edited by editing the master form.
[edit]

Display

  • Display the fields of the master form as normal.
  • Then display each set form, showing only the unique fields.
[edit]

Edit

  • In display mode the top "Edit" link edits the master form as per normal. The only difference is that any changes made here to common fields will affect the set forms.
  • On the display page each additional form has its own "Edit" link.
[edit]

Field groups

  • Master form fields in field groups use the master form as normal
  • Set form fields in field groups:
    • Controlled by the status use the status of master form when any form in the set is displayed/edited.
    • Controlled by a common field use the value from the master form
    • Controlled by a unique field use the value from the set form
[edit]

Setup

  • Each template has a "Repeating" option of "On" or "Off".
    • TemplateEdit.aspx
    • If sets are used then turned off we show a warning message (using JavaScript on "Off" click) that all set forms will be deleted leaving only the master forms. If the user agrees all the set forms in the sets are put in the bin. Those set forms and any other set forms already in the bin cannot be restored as long as sets are still "Off" for this process.
    • When sets are off the "Repeating" option in the field setup is hidden.
    • Default for new templates is "Off".
    • The template will also has a setting to define the link used to add forms to a set. This option is shown under the sets on/off option and is hidden with JavaScript if sets are off.
      • Can not be empty if sets are on
      • Default for new templates is "Add repeating fields"
  • Field setup has a "Repeating" option of "Yes" or "No"
    • Yes = unique field, No (default) = common field.
    • Editable only on the template setup and not the setup of the master form since we only want the possibly required data changes to occur during a sync.
      • Options are hidden on the edit field page of the master form setup.
    • Set forms can't have their field setup modified on their own. Going to the field setup for a set form just gives you the master form.
    • Common fields are indicated on the template list.
    • If a reference field has a parent that is unique then it can not be common. In this case it's repeating option will be checked and disabled.
    • A template does not require common fields to use sets.
    • Default for new fields or fields is unique (unchecked)
    • Best practice: The fields should be arranged so the common fields are on top so the master form is displayed more like the set forms below it, but this is not required.
    • Best practice: The field displayed as the form title should be a common field, but this is not required.
[edit]

Synchronization

  • A form added to a set uses the setup of the master form, not the template.
  • Field changed from unique (repeating) to common (non repeating):
    • Delete this field from a set
    • Creates a history entry for that changes
  • Field changed from common(non repeating) to unique (repeating):
    • Copies the current shared value
    • Creates a history entry for each field that changes
  • Form inclusion in a synchronization depends on the set status and archived flag. This means there is no way the user can ask for some forms in a set to be synchronized and others in the same set aren't. However, through server error or user intervention it is theoretically possible that a form in a set could be different than the master form.
    • If this happens it shouldn't affect much. Just display and edit this form using its own setup of which fields are unique (shown) and common (hidden). The next synchronization will clean it up.
[edit]

XML

For template download/import

  • Template tag "repeating" after "number". Contains up to two tags:
    • "enabled". Contains either "true" or "false". If missing assume false.
    • "addLink" Contains a string. If null or missing assume "Add repeating fields".
  • Field tag "repeating" after group. Contains either "true" or "false".
    • If missing assume false
[edit]

Status

  • The status of the master form is used by the all the forms in the set.
[edit]

Status triggers

  • Field changes to the master form change the status as normal if there are applicable status triggers set up.
  • Status triggers in the set forms are ignored. Changes to the set forms can never change the status of the master form (the status of the set).
[edit]

Notes

  • Notes are only added to and displayed form the master form.
  • Set forms are not allowed to have notes.
[edit]

Files

  • The files of the master form are used by the set and all set forms.
  • Other forms in the set are not allowed to have files.
[edit]

History

  • Shows the history of the master form as per normal, with the addition of:
    • New start and delete history events for set forms (saved in the history of the master form).
    • Edit history events from the unique fields only from set forms(saved in the history of the master form).
  • In other words, only the history of the master form is used. The set forms have no history.
  • See Form history (spec)
[edit]

Participants

  • The security of all forms in the group depends on the participants of the master form only.
  • The set forms have no participants of their own.
    • No email notifications except from the master form
    • Not counted in "participant in..." kind of links and views, including the attention list
  • Adding a form to a set, deleting a form from a set, and edits to the unique fields of any form in the set will trigger the unread notifications of the master form and update it's modified time.
[edit]

Owner

  • The owner of the master form is the owner of the set.
  • The set forms have no owner of their own.
[edit]

Actions

  • The actions of the master form are used by the set forms.
  • Set forms have no actions of their own.
[edit]

Global actions

  • Global actions are triggered only by the events and status of the master form.
  • The set forms never cause actions to be created.
[edit]

Views, Download

  • There is an option on the edit view page of processes with form sets enabled to determine if set forms are listed or not.
    • Repeating fields: Master only (default), List as rows
  • The option selected above affects how filters work.
    • When the forms are grouped (option "Master only") then filters need to look at all the forms within a set. In other words, if any set form would be shown then the master is shown.
    • When the other option is selected and every form is in the view then each form is treated individually.
    • Example: Common field agency reference, Unique field supplier reference.
      • Common: "AAA Networks"
      • Master supplier: "Qwest"
      • Set form 1 supplier: "Sprint"
      • If I am showing master only and I have a supplier filter limit to "Sprint" then the master is still listed because one of its set forms has that supplier. If the option was set to list all forms then the master would not be listed, but set form 1 would be (even though in the end the link shown in the row for set form 1 is going to take you to view that master)
  • New column "Form set" to match the import column.
    • Empty (null) if is master form (including if processes has form sets disabled)
    • Database ID if set forms (as used for imports).
[edit]

Reconciliation

  • Items are matched to the master form.
  • All forms in the set are checked for conditions.
[edit]

Archived

  • Only the master form matters. If it's archived, the set is archived.
  • Auto-archive by status then works as expected since only the status of the master form can be edited and it's shared by all forms in the set.
[edit]

Process summary, Labels

  • Forms in a set use the values from the master form for common fields and status. For unique fields they use their own values.
[edit]

Future

  • Maybe so changes to the "Referenced in..." kind of links to better show differences between a common and unique reference fields.
  • Edit the name/number of set forms.
    • The reason there is no set number at this point is there is an arguable lack of benefit of an arbitrary number. It's really just the data in the unique fields that defines a set form. Unlike master forms, set forms only need to be individually referenced when doing imports. Maybe an auto-generated integer based on the placement within a master form would be easier, on the other hand maybe it would be more prone to error, especially given and unclear model of the master being "1" or "0".
[edit]

Misc.

This feature was originally called "Form groups". It was changed to avoid confusion with all the other "groups" in RPM, especially field groups.

[edit]

Security

  • See "Participants" above
[edit]

History

Retrieved from "http://rpmsoftware.com/wiki/index.php/Form_set"
  • This page was last modified 15:39, 21 Apr 2008.
  • This page has been accessed 2260 times.