From RPM Wiki
| Table of contents |
Summary
Shells are an integral part of the Excel auto-complete functionality.
A shell is a special type of Excel file that is uploaded to RPM. When a user later does a download, a shell can be selected instead of a "Data only" (traditional) download and RPM will return the shell with the last worksheet filled in with RPM data. The first worksheets of the shell should contain some sort of formatted forms or reports that use macros, formulas, links, and functions to pull the data from the sheets populated by RPM. This gives RPM Excel auto-complete functionality for things like filling out order forms, invoices, reports with graphs, etc.
Download from
- Process, agency, rep, customer, account, staff, commission item view
- Form, agency, rep, customer, account, staff, commission item details
Complexity is in Excel
Most of the work is in building the shell. This keeps complexity like formatting and mapping out of RPM. This in turn keeps our development costs down and the interface simpler.
Data structure dependency
This arrangement means that the macros, functions and formulae are dependant on the data being put into the Excel file in a certain structure. To appreciate this, imagine the most simple implementation of this feature: RPM simply fills in the last worksheet with the same download it would have done without the shell and it's up to the user to make sure the view column order matches the macro. In this situation any change to the view columns would break the macro and you wouldn't know it until after the download. The only solution is to edit the view again or upload a new shell. It's obvious how this would be a big usability issue when all I want is to be able to make a view of some Orders and download them in the Qwest format. To make everything easier for the end users, the user who uploads a shell will also indicate which columns it's expecting and what order it's expecting them in.
Shell format
The leftmost worksheets will contain the user specified forms with formulas/links and macros written in terms of the data worksheet. The rightmost worksheet will be the data worksheet and will be supplied by the shell creator (since it is impossible to define links and formulas based on cells in a non-existant worksheet).
Unlike regular View-based exports, only one data sheet can be populated by a shell export. Multiple data sheet export would be impossible without defining some sort of naming scheme for the multiple data sheets. This in turn would probably require us to enforce a naming scheme on the vast majority of shells which will not require this functionality.
Shell columns
Similar to selecting columns for a view, every shell has its columns specified in RPM. When the shell is used for a download those columns and their order are used instead of the columns in the view. This protects the shell from changes made to the template, custom fields, and views. It also protects the users from having to know the structure of shells in order to use them. After a shell has been uploaded the user can still go and modify view columns. Even though the shell Excel file can't be changed after upload, this is important for situations like deleting a field from a template and replacing it with something else. As long as the data is equivalent, the same file could maybe be used (of course the user would need to update the shell settings with the new column).
Why not name instead of position?
It's possible to build macros that go off of column names instead of column position. While this may seem like an answer to the structure dependency issue, it isn't:
- Field name changes are almost as easy as position changes
- Shell column definition separate from view column definition is still required to make sure the required columns are present in the download
- Macros that depend on cell position are simpler to write and maintain than macros that lookup by name
Shell management
Shells are added (uploaded), edited, and deleted from a "Shell management" page in the "Information management" settings section of RPM. In RPM each shell has:
- Excel file. Saved in a similar fashion to attachments.
- Name. This is displayed in the download menu
- Category. One of the 14 "Download from" pages listed in the summary (see above)
- Columns. (see above)
Columns
Columns are specified using the same interface as columns for views, default template columns, and default commission columns.
The column options for a given shell are the same as those which are available for the item or view with which the shell is associated. For example, a shell for Agent views or for an Agency has the same column options as the Agency view. Further, the default columns for a new agency shell are the same as the current "All" view for Agencies.
The column options available for Process (or Form) shells will be the same as those which are available for the default staff view for a template.
Optionally, the user can indicate one or more column names using row 1 of the worksheet intended to be filled in with RPM data. When RPM analyses an uploaded shell, it will try to match as many columns as possible. If at least one column is discovered this way, RPM will then display that (those) column(s) instead of the default columns. The order will be copied from the Excel file. The user can then still change the columns in the shell setup as per normal.
Security
In all cases access to the view or details page and the permission to download Excel files is required to download it in any way including using a shell.
Staff users
- Shell management requires the "View, modify management" privilege
- If the subscriber does not have the Commission Module enabled, then they do not see the Commission Item Single or Commission Item View options when they are adding or editing shells.
- The user can add and edit shells for any template (or forms of any template) in the system as long as it is not in the recycle bin. This means that if a template is "turned off", or if the current user is of a role that cannot see the template, the user can still manage shells for it.
Agent users
- n/a
History
- Phoenix - Feature added
- This page was last modified 16:22, 7 Feb 2008.
- This page has been accessed 3472 times.