Form history (spec)

Category: The information that is saved is divided into categories. As with the old history, it is only the text values of names and data that we need to save, not keys to current table rows. However, unlike the old history, this information must be separated into a grid.
What: For each category there are several "What" options. This chart of Categories, What and Value will indicate what must be recorded.
Method: This is used to indicate which method the user used to do the "What" specified.
- Edit – The user manually used an "Add", "Start" or "Edit" link in the application.
- Import – The "What" occurred during an import
- Sync – The "What" occurred during form synchronization
- Single – Just the thing in question was deleted
- Child – This field was deleted because it’s parent field was deleted
- Multiple – The thing was deleted along with other things in a mass deletion
- Auto – The ‘What" occurred because of some sort of workflow logic.
- Copy – This form was started as a copy
- API - Done through the API
Value: This is usually what the field was changed to. There are some exceptions listed in the chart above.
- For multi-select fields list all values separated by comma + space. Example: "Sprint, Quest, AT&T"
By: The user who caused the "What". In the case of synchronizations and imports, it’s the user who started the sync or import. In the case of field groups, status triggers, and global actions it’s the user who made the field/status edit that caused it to occur.
Role: The role of the "By" user. For agent users it’s: "Agent {rep/manager}, {company}"
User ID: The master user table database key of the user

[edit]

The chart

Category	What	Method	Value
The form	Started	Edit, Import, Copy, Flow, API	If copy then "{form number}" If flow then "{process} {form number}"
The form	Deleted	Single, Multiple	n/a
The form	Archived	Single, Multiple, Auto	n/a
The form	Restored	Single	From trash, From archive
The form	Owner	Edit, Import, Copy, Auto(1), Special(6), API	{name}
The form	Status	Edit, Import, Auto(2), Special(6), API	{status}
The form	Number	Edit, Import, Special(6), API	{number}
The form	Source	Flow	to {process} {form number}
Participants	Added	Edit, Import, Copy, Auto(3), API	{name}
Participants	Removed	Edit, Auto(4)	{name}
Actions	Added	Edit, Auto, API	{action}; {date}; {name}; {status}{; "hidden"}
Actions	Edited	Edit, Auto(5), API	{action}; {date}; {name}; {status}{; "hidden"}
Actions	Deleted	Single	{action}; {date}; {name}; {status}{; "hidden"}
{field}	Edited	Edit, Import, Copy, Setup, Flow, Special(6), API	{value}
{field}	Edited	Auto	Cleared because of move
{field}	Deleted	Single, Sync, Child	{value}
{field}	Renamed	Edit, Sync	to {name}, from {name}
{field}	Restored	Single	{value}
{field}	Reference renamed	Edit, Import, API	to {value}, from {value}
Notes	Added	Edit, Import, Flow, API	{note}
Notes	Edited	Edit	{note}
Notes	Deleted	Single	{note}
Notes	Restored	Single	{note}
Attachments	Added	Edit	{filename}
Attachments	Deleted	Single	{filename}
Attachments	Restored	Single	{filename}
Set form ({ID})	Added	Edit, Import, API	n/a
Set form ({ID})	Deleted	Single	n/a
Set form ({ID})	Restored	Single	From trash
{field} ({ID})	Edited	Edit, Import, Copy, Setup, API, Renamed	{value}
{field} ({ID})	Deleted	Single, Sync, Child	{value}
{field} ({ID})	Renamed	Edit, Sync	to {name}, from {name}
{field} ({ID})	Restored	Single	{value}
{field} ({ID})	Made common	Sync	{value}
{field} ({ID})	Made unique	Sync	{value}
Approval	Choice	Edit, Auto(7), API	Pass {pass #}: {stage}: {choice(7)}{, }{comment}
Approval	Skipped	Edit, Auto	Pass {pass #}: {stage}
Approval	Completed	Special(8), Auto, API	Pass {pass #}: {overall result}
Approval	Aborted	Edit, API	Pass {pass #}
Approval	Forced	Edit, API	Pass {pass #}: {choice}{, }{comment}
{worksheet}	Added	Edit, Copy, API	{if copy: {From: {worksheet}}}
{worksheet}	Deleted	Single
{worksheet}	Restored	Single
{worksheet}	Renamed	Edit, API	to {new name}, from {old name}
{worksheet}	Edited	Edit, API	{"header"\|"footer"} changed(9)
{worksheet}	Table	Edit, API	{table name} {"added"\|"deleted"\|"restored"}
{worksheet}	Values	Edit, API	{table}: {value list}(10)

Use "Auto" when the owner is set because a staff user was deleted
Use "Auto" when it was a status trigger, for new forms getting their first level, or if the status level was from an approval result.
Use "Auto" when it was a global action or because this staff user deleted an existing participant who was the owner and so needs to be added to become the owner
Use "Auto" when the user was deleted
Use "Auto" when the action owner is changed because a participant was removed or a user was deleted.
"Special" method is when the edit was done by Special edit
The choice is "Approved", "Rejected", or "Skipped".
- "Auto" is the method when the result was created because of auto-skip. A manual skip creating a skip result gets the "Edit" method.
The "Special" method for the approval completed is only used when the result is forced.
We don't actually save the value, we just say and edit was done
Separate cells by comma and rows by semicolon. Example:
- "Voice quotes: Qwest,200,400;Sprint,100,600"

The "Notes" category is used for both "Notes" and "Notes for staff".
We don't need to keep track of editing of attachment descriptions
The {ID} is the id number of the set form. Example: "Set form (15234)"

[edit]

Common procedures

All history entries in the sections below are listed oldest to newest.

[edit]

New form manually

The form, Started, Edit
Participants, Added, Edit
Participants, Added, Auto (If a staff participant is added automatically)
The form, Owner, Edit
The form, Status, Auto
{FIELD}, Edited, Edit (For each field completed in the start wizard)
Any global actions or status triggers

[edit]

New form imported

The form, Started, Import
Participants, Added, Import
The form, Owner, Import
The form, Status, Auto
The form, Number, Edit
{FIELD}, Edited, Import (For each field completed in the importer)
Any global actions or status triggers

[edit]

Form copy

The first entry is a "Started" for "The form". This is followed by each participant, the owner, status (new), and each field. For each entry the method is "Copy" and the "By" is the user who started the copy (except for status, which is "Auto). Example (oldest to newest):

The form, Started, Copy, n/a
Participants, Added, Copy, John Smith
Participants, Added, Copy, Bob Jones
Participants, Added, Copy, Amy Anderson
The form, Owner, Copy, Bob Jones
The form, Status, Auto, New
MyTextField, Edited, Copy, Hello World
MyMoneyField, Edited, Copy, $1.00
Any global actions or status triggers

[edit]

Delete owner (user)

When a staff user is deleted any forms they owned would get

Participants, Added, Auto (add user doing the delete if they aren't already a participant)
The form, Owner, Auto (change to above user)
Participants, Removed, Auto (the deleted user)

[edit]

The grid

Sorting and paging: The grid allows sorting by any column and follows paging rules according to the user’s "Items per page" setting. The default sorting id by "When". Default sorting order, ascending or descending, depends on the user’s "Date sorting" setting.
Filter: In the category column each category will be displayed as a link. Clicking this link changes to a view where only entries from that category are shown. At the top of the grid where it used to say "View: All", it will say "View: Back to all". Clicking "Back to all" will return to the unfiltered view of all items.
- Example: Click on a field name in the category column to see only the history of that field. Click "Back to all" to return to the top.
Count: The grid will show the number of history items at the top. This number will change along with the view filter.
Columns
- "Category"
- "What"
- "Method"
- "Value"
- "When" (Date & time, hh:mm mmm dd, yyyy. Month day & year replaced by "Today" and "Yesterday" when possible)
- "By" (Name)
- "Role"
  - Staff: "{role name}"
  - Agents "Agent {rep/manager}, {company}"
- "User ID"
Download
- The grid has a link to download.
- As with custom views, all pages are downloaded and the filter is applied.
- The download always puts absolute dates, not "Today" or "Yesterday".
- Filename: "{process}: {number} History.xls".
  - Example: "Order O01234 History.xls"
- Worksheet names: "History {pagenum}"

[edit]

Read history

A separate grid under a "Read" tab displays a list of every time a form is marked as read for a participant.

[edit]

Columns

When
Method
By
Role
User ID

[edit]

Data

The data is the same as for the regular form history except for "Method" which is either "Single" (the user viewed the form) or "Multiple" (The user used the "mark as read" option in a view, even if that just affected 1 form).

[edit]

Security

[edit]

Staff users

Staff users who can view a form can view it’s history.

[edit]

Agent users

The "History" link and page is hidden from agent users.

[edit]

Use Case

Bring up a specific form. Click "View history" to see a complete chronological history of everything done to this form. Sort the "By" column to look for all the changes by a specific user. Find a field they changed and click on the field name to see everything done to just that field. Click download to get the history of that field as an Excel file. Click "Back to all" to view all the history items again. Click download to get the whole history for this form as an Excel file.

[edit]

History

Venus: Process management added along with the first, basic history (we assume)
Rockefeller: Major improvements including new UI, more detail, download. For existing forms previous history was kept in old format (not migrated).
Ganymede: New history entries needed for the Form set feature. User ID column.

Retrieved from "http://www.rpmsoftware.com/wiki/index.php/Form_history_%28spec%29"

This page was last modified 22:57, 28 Feb 2011.
This page has been accessed 7829 times.

History