Referral (spec)

From RPM Wiki

Summary

This is an idea for a new referral system that will replace the existing Agency referral functionality. In short, instead of being attached to one thing like an account or agency, each referral will be their own entity with a full details page. Each referral will still only pay one agency, have the same notes, and the same commission rate options. However, there will be three big improvements:

Each referral will have a list of what it does (include) and does not (exclude) pay on. The design is a kind of a blend of view filters and reconcile conditions.
A single commission item can pay any number of referrals.
A referral can have optional last run

Examples

1. Everything for one agency

The agency "Bravo" was brought to the master agent by existing agency "Alpha". For this Alpha will be given a 2% net billed override on everything new Bravo sells for one year. The exception is Qwest spiffs which are passed through at 100% so there is no margin to share.

A referral would be created with Alpha as the "Pay to" agency and a 2% net billed rate with override type.
The only include would be agency Bravo. This means every item sold by Bravo will be eligiable for this referral as long as it doesn't also meet an exclude
The first exclude would be an account group that is Bravo's old business they brought with them (since the agreement is just to pay the referral on new business). The other exclude would be the Qwest commission group "Spiff".
The last commission run is set to one year from the first so that the referral will automatically stop paying as per the agreement.

2. Affiliate deal

The master agent has made a deal with a University association "Educom" where they bring university customers and get 25% of the agent's commission

Educom would be added as an agency and a referral would be created with Educom as the "Pay to" and a 25% agent comm. rate with deduction type.
Applicable customers will be added as includes

3. Referred supplier

Agency "Delta" was key in completing the master's new contract with supplier "Sprint". The arrangement is then that Delta will get a 1% override on everything any other agency sells to Sprint starting in the August run when that contract takes affect.

A referral would be created with Delta as the "Pay to" and a 1% net billed rate with override type.
The only include would be supplier Sprint.
The agency Delta will be added as an exclude since they don't get the override on their own Sprint sales
The referral term will specify a first run of "Aug 2008"

Referral details

The design is loosely based on account groups.

Things such as the pay to, type, notes, and commission rule remain unchanged from the old design. The big change is that now each referral has its own page instead of being in a web box.
New page
- /Staff/Referral.aspx
- Title: "{Pay to agency} {Rate}"
- Example: "TelcoPro 2% net billed"
- This is also shown as the name in the recycle bin. The recycle bin type is "Referral"

Pay to

No change. Each referral pays one agency.

Type

No change. Each referral is an "override" or a "deduction".

Override: Paid in addition to the full agent commission (comes out of the subscriber's pocket).
Deduction: Subtracted from the agent commission (comes out of the selling agent's pocket).

Notes

No change. Each referral has 2 description-style (single entry) notes.

Note for staff
Note for agent

Commission rate

No change. The user selects an amount and a rate type.

Add

Adding a referral goes to the referral info edit page.

A new referral will have no includes and until some are added the referral will not apply to anything.
Adding a referral triggers the calculate required flag.
A referral can only be added if there is an open commission run.
- If there isn't, the add link leads to an error page: "An open commission run is required"

Copy

An existing referral has a copy link that launches the add wizard but with the fields filled in.

The notes and commission rate are copied.
All includes and excludes are coppied.
It is fine if the user leaves everything the same. There is no check for a unique combination because the way the include/exclude system is designed, there may be a need for multiple referrals to satisfy one agreement.
Copying a referral triggers the calculate required flag.
A referral can only be coppied (added) if there is an open commission run.
- If there isn't, the copy link leads to an error page: "An open commission run is required"

Edit

The pay to, type, commission rules, term, and notes are all shown in an "Info" web box and all edited together on an edit page.

A pay to agency is required.
Editing a referral triggers the calculate required flag.

Delete

Referrals can be deleted and restored from the bin. While in the trash the referral does not apply and is not listed. Also, it is not included in counts in referral web boxes on other things (see Cross reference below).

Deleting a referral triggers the calculate required flag.

Things get a little complicated when the referral was used in past run. Similar to what we did with splits, when a referral has been used in closed run it is never deleted. When the recycle bin is emptied, any such referrals instead of being erased go into a permanent hidden state. They can not be edited and are not considered when calculating future runs so as far as the users can see they are gone. However, they must stick around to provide notes for those past items.

Term

Every referral has a first run and an optional last run.

The start run by default is the open run, or if there isn't one, the next run.
- The user can select from 5 years worth of runs starting with the default run above.
- This allows the user to put in a rule that won't start for a while
The last run is either "n/a" (default) or a commission run.
- The user can select from 5 years worth of runs starting with the default run above.
- An error is shown if the last run is before the start run (but they can be equal since they are inclusive). "A term of at least one month is required"
The Referral is listed even if it's term has passed. It's up to the user to delete a referral to make it go away.
The start and end are inclusive.
- Example: a start of Jan 2008 and an end of Feb 2008 will mean that the referral is used in both those runs.
Changing the referral's term will set the calculate required flag.
This is displayed and edited in the referral's info web box.

Includes & excludes

These are things that are checked in the commission item to see if this referral applies. A referral must have at least one include and can have any number of excludes.

Category

An include/exclude has one of the following categories:

Agency (selling)
Supplier
Customer
Account
Account group
Product
Commission group

A user can add multiple includes and excludes of the same category (see Calculation below).

List

Include and exclude are separate web boxes on the referral details page. Each one has a list of the includes/excludes it and an "Add" link in the toolbar.

Simple list style (no headers) with 3 columns. First is the category (Account, Product, etc.). Second is the value (the account, the product, etc.) as a link (gridlink style). Third is a "Remove" link.
- Sorted by category then value.

Add

2 page wizard. First page the user selects the category. The second page is the value of the include/exclude. The method of selection will depend on the category.

Account, Account group, Product, and Commission group selection also requires a supplier field on the page. They do not requrie an existing supplier include/exclude and are not related to other include/exclude and there are no parent/child relationships.
If there is an existing include or exclude in this referral with the same category and value then show an error and put the user back on page 2: "A unique combination of category and value is required."

Remove

Clicking the remove link in the list erases that include/exclude.

There is no edit or recycle bin functionality for includes/excludes since they are so simple.
However, if something like an account is deleted then any includes/excludes it is the value of are deleted and possibly restored with it. While the account (or whatever) is in the trash any includes/excludes that depend on it don't apply and aren't shown in the referral.

Misc.

There is a slight naming difference between view filters where positive filters are called "limit to" while referrals "include" things. This is because a blank view starts out by including everything then reducing the result set while a referral includes nothing at the beginning.
If an account group is copied then any excludes or includes it was in are added for the new group

Calculation

Like reconcile conditions, a commission item must meet all of the includes to pay the referral (kind of, see below). In addition, it must also match no excludes. In other words, a single exclude being true will wipe out all the includes.
- Like view limit to filters, referral includes of the same category are treated as OR. In other words, if I have two account includes then the commission item only has to match one of them.
The current calculating commission run must also fall within the referral's term.
The previous rule of maximum one referral per type per item is gone. A commission item can have any number of referrals.
The previous rule of not paying a referral if the pay to agency is also the selling agency is gone. That's now up to the subscriber to manage with referral includes/excludes. In some situations it may even be the desired setup.

Referrals grid

Staff users will have access to a list of all referrals. The page will have sorting and paging as usual. The columns will be hard coded.

New page: Staff/Referrals.aspx

Columns

(View link), Pay to, Type, Rate, Note for staff, First run, Last run

Pay to, Type, Rate, First run, Last run are sortable
Default sorting is by Pay to agency A-Z

Filter

Filtering is available only in a style similar to temporary views where you start at another page.

See Cross reference below.

Cross reference

The details page of suppliers, customers, accounts, account groups, agencies, and products there will have a "Referrals" web box that lists one grid of the referrals the thing is involved in.

The gridList grid class has columns, but does not show headers
Columns
- "View" link
- Pay to
- Involvement. This is "Include", "Exclude", or "Pay to" (pay to to is only possible on agency page)
- Rate
- Type
- Note (using icon that shows notes on hover)
Sorting is by involvement with the pay to rows, then the includes, then the excludes. Secondary sorting doesn't matter.
If the thing is involved with a single referral in more than one way then the referral is listed once per involvement. Combining the referrals into one row may be a better design, but this is a rare situation and separate rows is simpler.

Commission reports

Agency summaries

The agency commission summary shows

In the summary grid the total incoming referral amount
Beside that is a link to a temporary comm. items view that is the items paying a referral to that agency
Under the "Referrals" tab is a list of the referrals with items paying this agency in this run. Columns:
- ("View" link to referral page)
- "Items" (shows an integer count of the items this run with a link to a temporary comm. item view of items for that referral)
- "Type"
- "Rate"
- "Note for agent" (The complete note text, not the icon)

Items paying a referral (Staff)

No change. This page lists agencies receiving a referral and breaks out the amount by override, deduction, and total referral.

It also has a link to a temporary comm. items view that is the items paying a referral to that agency.
Link from comm. run task page

Items paying a referral (Agent)

This is a page that looks a lot like the comm. items view page, but is for agent manager users to see items paying their agency a referral.

Staff users don't need it because they have custom and temporary views
Columns: TODO

Item details

The calculation web box shows the referral amounts for override and deduction if applicable. The change is that now each number is technically a total instead of just a single referral.
The referrals web box will list all referrals that apply to this item in a simple grid list style. Columns:
- Pay to, Type, Rate, Note icon (shows all notes depending on the user, see Security), "View" link (no header, staff only)

Comm. item views

There are two temporary views:

Items paying a referral to a certain agency
- Link from "Items paying a referral" page
- Link from the agency comm. summary page
Items paying a referral because of a certain referral (new)
- Link from the referral details page
- Link from the grid under the referrals tab on the agency comm. summary page

Security

Fundamentally no change, but the new functionality will require new applications of the existing security theory.

Theory

Agents see referrals of any type that pay them.
Agents see referral deductions paying someone else on items they sell.
Agents see referral deductions paying someone else on items they are receiving a referral payment of any type from.
Agents never see override referrals paying someone else.

Staff users

Viewing the referrals grid, details page, and web box on other details page requires "View agency schedules"
Adding, editing, and deleting referrals requires "Edit agency schedules"
Viewing the commission results depends solely on the permission required to view the commission item or summary in question.
Only staff users see the cross reference referral web box on other details pages and then only if they have the "View agency schedules" privilege.

Groups

commissions.agentSchedules
commissions.agentSchedules.edit

Agent manager

The pay to agency
- Agent managers with a "Agent commission" of "Not hidden" see a report of all referral amounts being paid to them.
- Furthermore, if the agency also has the "See full referral item details" permission then that agent manager can also see the item details of commission items paying their agency a referral.
  - In this case the agent manager will see all deduction-type referrals on the item when they look at the details page of the item, but they will only see referral overrides that pay their agency.
When an agency manager is looking at referrals that pay them they see the "Note for agent" for each one.
The selling agency
- When looking at a commission item sold by a rep in their agency, if the manager has "Agent commission" of "Not hidden" they see any referral deductions on the item and the "Note for agent" for each one.

Agent rep

When looking at a commission item they sold, if the rep has "Agent commission" of "Not hidden" they see any referral deductions on the item and the "Note for agent" for each one.

Example

This item was sold by rep "John Smith" of agency "Alpha". It had 3 referrals, a deduction to agency "Bravo", an override to agency "Charlie", and another override to agency "Delta". The Bravo and Charlie agencies have the "See full referral item details" permission, Delta does not. This example will assume all users listed below have "Agent commission" of "Not hidden".
- John Smith and any managers from Alpha will see the referral deduction and it's "Note for agents". No one from Alpha will ever see the override referrals or their amounts.
- A manager from Bravo will see his pay to amounts. He can also click on the item paying the referral and see his deduction referral paying him and it's "Note for agents". He does not see the other referrals on that item details.
- A manager from Charlie will see her pay to amounts. She can also click on the item paying the referral and see both the referral deduction paying Bravo and her override deduction. She sees the "Note for agents" on both referrals. She does not see the override referral paying Delta.

Migration

All existing referral agreements will migrated to the new system

This is not necessarily going to be a seamless experience for subscribers since they may have been using the "1 referral per type per commission item" to have some referral rules take precedence over other rules.
- I remember telling someone once they could get the effect of an account exception on an agency-level referral by adding a referral of the same type on the account but at 0%. I'm not sure if anyone actually implemented that. It will be up to subscribers to rebuild any such exclusion functionality using the new includes/exclude functionality.

Future

Ideas

Referrals that pay reps, staff, or even some new partner entity.
Full or partial custom view functionality for the referrals grid.

New pattern

A similar design will likely be used when we overhaul addendums in the future. Instead of a pay to agency, the addendums will have a single selling agency.

History

Referrals were added in version 1 and remained mostly unmodified until...
Judge: The referral overhaul outlined on this page

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

This page was last modified 03:21, 21 Oct 2008.
This page has been accessed 8162 times.

Log in

History