From RPM Wiki
| Table of contents |
Summary
An import used to create or update process forms from an Excel file
Per process
Form imports are always done within one process at a time.
- A process must be "On" for imports to be done (See Process management)
- If there are no processes that are "On", the import wizard generates a "No eligible processes" critical error.
File and data format
- See the Import Excel file page
- Start with a pre-made blank file or create your own using the column spec.
Common functionality
Start with the Import and Common import functionality (spec) pages.
Form number
- "Number" - The number of the form to update or create
- "New number" - Used to change an existing form's number
As covered in the Common import functionality (spec) page, the form number is used as the unique identifier. Here are some additional rules for the form importer:
New (create) vs. existing (update)
The "Number" column is used to determine if this is a new form that needs to be started, or an existing form that needs to be updated. If the "Number" column:
- Is empty: This is a new form that gets an auto generated number
- Has a number that isn't used: This is a new form that gets that number
- Has a number that is used: This is an update of that form
Duplicates
A duplicate is a row that has the same number as another form. Duplicates are not imported. Two checks are made to determine if there is a duplicate:
- First the "Number" column must be checked. If a row has the same value in this column as another row, they are considered duplicates.
- Also, the "New number" column must be checked to make sure we won't end up with forms with the same number.
- If some rows have a value in this column but others don't, use the "Number" column for the ones that don't. Example: Row 1 has a "Number" of "123". Row 2 has a "Number" of "456" and a "New number" of "123". Those rows are duplicates.
Example: Two rows trying to change the same number:
| Row | Number | New number | |
|---|---|---|---|
| 1 | 123 | 456 | DUPLICATE |
| 2 | 123 | 789 | DUPLICATE |
Example: The final numbers would conflict:
| Row | Number | New number | |
|---|---|---|---|
| 1 | 123 | 456 | DUPLICATE |
| 2 | 456 | DUPLICATE |
Example: This situation is fine. Essentially we have two forms swapping numbers:
| Row | Number | New number | |
|---|---|---|---|
| 1 | 123 | 456 | OK |
| 2 | 456 | 123 | OK |
Example: These rows all conflict:
| Row | Number | New number | |
|---|---|---|---|
| 1 | 123 | 456 | DUPLICATE |
| 2 | 456 | DUPLICATE | |
| 3 | 123 | DUPLICATE |
Auto-generated
A blank "Number" will result in a new form with an auto-generated form number (See Process management). Auto generated numbers are assigned after all "New number" changes have been made. This means:
- Numbers in the "New number" column are not available to be assigned as new numbers.
- If a form gets a new number and it's old number is not taken by another row's "New number", then that old number is now available to be assigned as an automatically generated number.
Additional
- If the "Number" column is empty, but the "New number" column has a value, consider the "Number" to be equal to the "New number".
Form sets (Repeating fields)
New column for handling repeating fields (See Form set) with the import: "Form set".
- If the template has repeating fields (form sets) disabled then ignore this column
- Else:
- If the row's Number column is blank so a new master form is being created and auto-numbered, ignore the Form set cell. Any unique fields imported will fill in the master form only. No set forms will be created.
- Else, the Number is an existing or a designated new master form.
- If the form set column contains "add" (case insensitive) then create a new set form for that master form and fill in any unique fields in the import.
- If the form set column contains an integer that matches the ID of an existing set form for this master form, then update that set form with any unique fields in this import.
- If the form set column contains an integer that doesn't match the ID of an existing set form for this master form, or it matches a set form in the trash, then add a new set form. This new set form will get an auto-generated ID (as all new set forms do) so will lieley get an ID that doesn't match the import value, if it was even an integer.
- If the form set column is empty or has anything else then this row will not create or update any set forms and any unique fields imported will fill-in/update the master form.
Effect on duplicate
If set forms are enabled then the same form number is allowed as long as the form set column doesn't contain any duplicate integers or multiple blanks. Multiple adds are OK.
Assume 123 is an existing master form number and 34534 is an existing set form ID in that master form.
| Row | Number | Form set | |
|---|---|---|---|
| 1 | 123 | 34534 | OK |
| 2 | 123 | add | OK |
| 3 | 123 | add | OK |
| 4 | 123 | OK |
Two sets of duplicates:
| Row | Number | Form set | |
|---|---|---|---|
| 1 | 123 | 34534 | DUPLICATE |
| 2 | 123 | 34534 | DUPLICATE |
| 3 | 123 | DUPLICATE | |
| 4 | 123 | DUPLICATE |
Affect on import form count
The form counts in the wizard (new & updated) include set forms. To make this more clear, if a process has form sets enabled then the messages include "or set forms".
- Example: "2 forms or set forms will be updated"
Unread option
There is an additional option shown only in the form import. It is set separately for new (create) and existing (update) forms.
- Checkbox: "Mark forms as unread, send notifications"
- Default is unchecked for both
Create
- Unchecked
- Different behavior from adding a form by the UI.
- The form is considered "read" for all participants added by the import.
- No notifications will be sent for these forms because of this import.
- Checked
- Same behavior as adding a form by the UI.
- The form is "read" for the user doing the import if they are a participant.
- The form is "unread" for the other participants and they will get a notification.
Update
- Unchecked
- Different behavior from editing a form by the UI.
- The "read" flag of all existing participants is left unchanged from whatever it was before the import.
- The form is considered "read" for any participants added as a result of the import.
- No notifications will be sent for these forms because of this import
- Checked
- Almost the same behavior as editing a form by the UI
- The "read" flag of the user doing the import is not changed if they are a participant.
- This is different from editing the form in the UI since a UI edit requires visiting the form page which would have made the form read. Since the user doing the import may not have seen existing edits made by other participants, we don't presume to change their flag.
- Existing participants other than the user doing the import:
- If the form was already "unread" then it remains that way for the participant and they do not get a notification.
- If the form was already "read", and if at least one edits made to the form is visible to the user, then the flag is changed to "unread" for the participant and they will get a notification.
- New participants other than the user doing the import get an "unread" flag and a notification.
Notifications
When the above rules states that a notification is sent to a user, that notification is still subject to some settings.
- First is the subscriber setting that can turn off notifications for all users.
- Second is the user's notification setting overall and for each process.
In other words, when the business rules say a notification will be sent, it really means a notification is eligible to be sent.
Settings
There are some settings for the form import that are managed in the settings section. These settings affect all processes for the subscriber.
Create new
If an agency, customer, or account field is imported and the name is new, add the agency, customer, or account to the system.
- Create agencies, customers, & accounts:
- Yes (default)
- No
Agent participants
If an agency or rep field is imported, give the appropriate agent user access to the form. This is only done if agent users are allowed to see forms in that process.
- Add agent user participants:
- Yes (default)
- No
Staff participants
If a staff field is imported, give the appropriate staff user access to the form. This is only done if that user belongs to a role that has "Limited" or "Full" access to this process.
- Add staff user participants:
- Yes (default)
- No
Security
Staff users
- The "Import forms" privilege is required
- Also, a "Full" privilege for a process is required to import forms to it.
Agent users
- n/a
Modules
The "Process management" module is required
History
- Earth: Feature added
- Luna: Added the ability to import status, owner, and multi select lists and the ability to automatically add agent participants.
- Mars: Speed improvements
- Phobos: Added the overwrite option
- Ceres: Added improved error reporting that lists rows with problems
- Rockefeller: Speed improvements
- Pathfinder: Combined the previously separate "Create" and "Combine" methods and added the ability to set the form number. These changes came along with some UI changes including moving some of the options from the wizard to the settings area.
- Ganymede: Form sets (repeating fields)
- This page was last modified 15:41, 4 Jun 2009.
- This page has been accessed 4037 times.