Feature Specification

Feature Name: Advanced Sales Commissions

Overview

This functionality is sponsored by the Highlander Project. The intention is to handle complex commissioning scenarios in a multi-store retail sales environment. This module will allow time phased commission plans to be created that can be managed at a high level, such as by product or sales rep groups, down to extremely granular detail including individual sales reps or items. The system must allow tracking and reversal of commission payments, however, the presumption is payroll is handled externally so the main goal will be to accumulate and post commissions that are due to a payroll interface.

Advanced Sales Commissions should be created as an add-on to xTuple ERP using its own schema with UI business logic constructed using the xTuple Screen builder and Javascript extensions. This is necessary primarily to make sure there are no conflicts with Highlander intellectual property issues. By keeping the commission interface separate, it can be cleanly separated from standard xTuple functionality. The goal should be to abstract businesses logic to such an extent such this module could be repurposed in other environments, however, it may turn out that this functionality is so specific it only applies to the Highlander implementation. The architecture, therefore, must be designed at the outset with that possibility in mind. If nothing else, the level of functionality called for here goes far beyond the needs of the typical small business, so even if this capability were offered to the entire xTuple community, it would make the most sense to manage it as an advanced extension to the core system.

Advanced Sales Commissions depends new xTupleERP core functionality to manage employees in the system described in issue tracker log 6736.

Functional Requirements

  1. Ability to manage commission payments for retailer employees.
  2. The system shall accrue sales commission for the sales representatives.
  3. The system shall allow a user to create multiple commission plans.
  4. The system shall allow a user to select a specific employee or an employee group to calculate commissions for
  5. The system shall allow any pay plan to be assigned to a user
  6. The system shall allow dollar amounts to be assigned to any sku or product
  7. The system shall allow for a dollar amount to be assigned to different service types per service provider
  8. The system shall allow for a dollar amount to be assigned to multiple rate plans
  9. The system shall allow for a plan and its details to be duplicated easily and updated to applicable users without going to each user (batch update)
  10. The system shall allow for a plan to be assigned to a GL account for accounting purposes a debit account, and a credit account.
  11. The system shall allow for a user to assign commission plans to a User/ Employee
  12. The system shall allow for a user to create unique names per pay plan
  13. The system shall allow for a user to have or belong to a manager, supervisor or area manager for tracking of sales commissions.
  14. The system Shall allow for a User to post commissions to each customer invoice
  15. The system shall allow for a user to print out a payroll history
  16. The system shall allow for a user to run a commissions report
  17. The system shall allow for a user to Run/Calculate Commissions
  18. The system shall allow for a user to set up multiple commission levels per Employee
  19. The system shall allow for adjustments to be made to an employees commissions from the draft and posted to the appropriate chart of accounts
  20. The system shall allow for deleting new activation tiers prior to payroll running
  21. The system shall allow for multiple promotions to be assigned a dollar amount
  22. The system shall allow for plan to have a calculation basis. Invoice, order, receipt etc.
  23. The system shall allow for the following commission plan types: Gross sales, New Activation, Production Bonus, Promotion, Rate Plan, Programming, Sku/product, Service types. Net profit, Advertising Campaign.
  24. The system shall allow for the user to assign the check number that paid the commissions
  25. The system shall allow for the user to save the draft or modifications, for later processing.
  26. The system shall allow for Tiers to be assigned to Gross Sales details. From amount, To amount, Percentage pd.
  27. The system shall allow for ties to be assigned to New Activation plans, Base commission, 1-10 receivers, and a from qty to qty,
  28. The system shall identify the user/employees pay period, hourly rate, salary etc.
  29. The system shall keep a history of all invoices processed per payroll, and store them under the users personal commission tab in the user profile.
  30. The system shall keep a history of each users payroll under the commissions tab of the user
  31. The system shall show a user any outstanding payments still expected from a Service provider
  32. The system will prepare a draft version which can be reviewed and adjusted if necessary
  33. They system shall allow a user to select a cutoff date for invoices to be processed or calculated
  34. They system shall allow for a user to withhold / for payment later
  35. Sales Orders shall be able to support split commissions.

New Terms and Definitions

This is the place to define new words and phrases to be used in the application and the documentation. If this feature introduces a new concept or changes the semantics of an existing concept in the application then define it here. Define it even if you think the definition should be obvious, since your definition might not match the definition used by the reader, like so:

Related Existing Functionality

xTuple currently supports the creation and maintenance of Sales Reps who can be assigned a commission percentage. The percentage of commission is the default number that appears on Sales Order and A/R documents assigned to that sales rep. Two commissions reports exist that summarize commission accumulation against sales history, but do not take A/R history into account even though commission data is stored there. The commissions may be flagged as paid by drilling to the sales history information detail of any sales history report, and checking the commission "paid" checkbox.

The existing pricing structure works similar to the requirements in that either dollar amounts or percentages can be assigned to items in a variety of ways. Also tax structure is similar to some commission requirements here in that it can be divided across multiple entities and is calculated at the line item level on a sales order.

Similar and Related Requests

Conflicting Features

Several windows have a sales rep. associated with commission percentage for the entire document. This functionality prescribes the ability to assign dollar amounts by line item in a similar manner to taxes.

User-Level Functionality

All functionality added by this module will be managed with Package Manager functionality that is grouped together as a removable extension from xTupleERP.

A script will be created that adds an extra tab to Sales Order Management called "Advanced Commissions." The Advanced Commissions tab will have a checkbox to enable or disable advanced commissions. All other optional advanced commission defaults will be stored on this tab.

When enabled Advanced Commission Schedules will be available under the Sales > Item Pricing menu just above the menu separator as "Commissions." The first menu option under Sales > Commissions will be Commission Schedules.

Describe the menu changes and overall application structure changes here then get detailed in the subsections.

Window Changes

What windows do we expect to change?

What windows do we expect to eliminate?

What windows do we expect to add?

Insert screen shots of window mock-ups like this:

Describe what each window does, what its fields mean, what the buttons do, what right-click menu items are available in the list views, etc.

Report Changes

What reports do we expect to create, eliminate, or change?

Batch Manager Changes

What functionality do we expect to add to, remove from, or change in the Batch Manager?

Usability Considerations

How do we think this will affect user access to existing functionality?

What problems do we anticipate users might have with this functionality and how can we minimize the impact of these problems?

What errors or abnormal situations do we expect users might encounter during normal processing and how can we make it easy for the user to fix these problems using the application?

Problems and Alternatives

What might go wrong with the solution described in this document?

Why might this not be the best solution?

What are the limitations of this approach? What's missing that might be desirable?

Describe briefly other ways to solve the basic problem and the advantages and disadvantages of each alternative.

Justify the chosen solution or argue why one of the alternatives would be better. Be as broad as possible here, since an important purpose of this section is to provide alternatives in case the initial attempt at implementation encounters a significant implementation block.

Internal Design

Now that we have defined what we have to do and how we think it should look to the user, we can describe the internal structure of the application. If possible, outline the architecture of the feature implementation here. Then in the sections below describe the changes and additions to the application to create this architecture.

Basic Algorithms

Are there particular algorithms required to implement this feature? If so, describe them here. 

If you are going to outline a particular algorithm in pseudo-code
    put it in a programlisting
    try to limit lines to approximately 80 characters
    try to limit programming constructs while still being clear about intent
end if // a programming construct that may be unavoidable to maintain clarity

Custom Widget Changes

Do we expect to modify existing custom widgets to support the windows described above?

What new custom widgets will we need? Will they be derived from existing widgets? What behavior do we expect from them?

Schema Changes

What changes do we anticipate making to the database schema? New tables? Views? Indexes?

The new whatever-you-call-it table

Column Name

Description

Data Type

Comments

field1

Describe me

data_type

how it's used

foreign_key

Describe me

integer

foreign key to other_id

enum_field

Status or similar field

character(1)

Can take one of the following:
* A value
* Different Value
* Final Value

What privileges do we need?

Privileges for feature

Name

Description

MaintainWhatever-you-call-it

Can Add/Edit/Delete stuff

ViewWhatever-you-call-it

Can View stuff

Stored Procedure Changes

What stored procedures do we expect to create, eliminate, or change?

Performance Considerations

How will this feature impact the performance of the application overall?

Error Handling

What internal errors do we anticipate might occur?

How can we best hide them from the user, prevent them, or fix them automatically?

QA Considerations

Does this feature require any special tools or data to test? Is it testable (some features may be hard to reach from the user level)?

What are some anticipated areas of concern that require special attention?

Documentation Considerations

Is there a significant documentation impact?

Does the feature require a standalone essay or only field-level descriptions?

Release Considerations

What release would we like to target?

What is the potential impact on a release if we don't finish in time?

What happens if we only get some of the functionality done?

Are there any pieces that would be useful on their own?

Are there any dependencies on other features or applications (such as Qt 4 or a particular release of OpenRPT)?

What is the anticipated impact on users, particularly those who have customized the sources, reports, and database schema?

AdvancedSaleCommissions (last edited 2009-01-06 22:20:18 by ptyler)