Warning: This tool is an advanced feature and should be used with the guidance of an experienced compensation plan expert.
The Compensation Plan XML page is where you create or edit your commission template using an EXtensible Markup Language (XML) editor.
What We’ll Cover
- Enabling the Page
- Compensation Plan Conversion
- Finding the Page
- XML Editor Features
- Viewing the History For: Pop-up
- Creating a New Template Name
- Creating a Basic Compensation Plan
- Stats and Projected Commissions Template Names
- Adding Rank Values to the Database
Enabling the Page
To use this feature you’ll need to enable it in Advanced Settings > Commission > Compensation Plan Editor > Select the Enable XML Editor check box.
The EditCompPlan() permission needs to be enabled in order to use this feature.
Read more: Assigning Employee Permission Roles
Compensation Plan Conversion
If you have had your compensation plan previously coded and you’d like to use the Compensation Plan XML page, there would likely have to be a conversion. Contact your DirectScale account manager for details about compensation plan migration.
Once migrated, you’ll be able to use the Compensation Plan XML page as long as the above settings have been enabled.
Finding the Page
In Corporate Office, navigate to: Commissions > Compensation Plan XML.
XML Editor Features
Template Name - Select a previously saved template. The template name is defined in the XML:
Typically, the template name is the same as the period it represents (Weekly, Monthly, Bi-Monthly, etc.).
Important: Revisions should share the same name as the template so that the version History is shared between them. Templates can only be committed once per commission period. Volume Adjustments and Rule History are tied to the template name and are shared by all the template’s revisions.
Template Revision - Specific version of a template. Your cloned templates appear in this list.
For example: if you have a template named Monthly, you can have cloned revisions named Monthly-workInProgress, MonthlyTestingNewBonus, etc. This allows you to test changes without affecting the main template.
Once you want your revision to become the main template, it’s recommended that you copy/paste the revision’s XML into the main template’s XML Editor, change the
<ComPeriod>name, and click Save and log your commit. This way, you will have a single template with a full History of different version you can revert back to.
Save - Commit the changes to the template. Once clicked, a pop-up opens with the option of adding an optional commit message. The commit is logged in History.
Saving also validates the XML, will display a message, and highlight the errors. You can save changes even if there are validation errors to allow you to save your work-in-progress until it is complete; however, revisions with errors will not show as templates that can be used for Commission Profiles.
Clone - Allows you to create a copy of an existing template as a starting point for a new one. Cloned templates appear in the Template Revision dropdown. This will also carry-forward all of the original’s History.
Note: Clone will copy from the current XML displayed in the XML Editor not the most recent save; therefore, your cloned revision may not match the original revision if you had unsaved changes.
Download - Download an .XML file of the template.
History - View and compare saved versions of a template. Opens the History For: pop-up window. This functions as a Version Control System that allows you to see previous versions and then copy/paste the old versions into the XML Editor to revert back to it.
Delete - Delete a template. A pop-up will open requesting confirmation.
Search Bar - Search for terms in the Documentation section.
Quick Start - A helpful link to this article.
Documentation - Lists and defines XML syntax options that can be used.
- See descriptions of the parameters for that option.
- Copy the syntax to your clipboard where it can be pasted into the XML Editor.
XML Editor - Create or edit a template. The XML is then used to create the internal components used to run Commission Profiles. Templates with correctly formatted XML can be selected when running a new profile.
Viewing the History For: Pop-up
- View - View the version’s XML. Click the View History button to return to the History For: pop-up window.
- Compare - Select any two versions to compare their XML.
- Compare Selected - Click once two versions have been selected. The pop-up will show the two versions side-by-side, where you can compare their differences. Copy/paste the XML into the XML Editor to revert back to a previous save.
Creating a New Template Name
Click the Clone button to make a copy of an existing template.
A pop-up window opens, where you can give the copy a name. Click Clone to confirm.
The pop-up closes and the cloned copy becomes a Template Revision of the template you cloned.
To create a new Template Name, change the
<ComPeriod> Name attribute to the clone name.
Every template name must have a revision and
<ComPeriod Name=""> with the same name to function properly. Template Names and Template Revisions are case sensitive and can’t be longer than 50 characters.
Click the Save button and add an optional commit message. Click Save to confirm.
Refresh the page to see changes.
The Template Name dropdown now shows your new template.
Creating a Basic Compensation Plan
Step-by-step guide: How to Create a Basic Compensation Plan
Stats and Projected Commissions Template Names
To define your commission stats template:
Select one of your commission templates (Weekly, Monthly, Quarterly).
Usage="CommissionRun, StateStats, RealTimeStats"in the
Enter the template name in Stats Template Name in Administration > Advanced Settings > Commissions.
Projected Commissions Template
In Administration > Advanced Settings > Commissions.
Under the Commission Profiles section, to enable the associate to view their projected commissions in their Web Office > Pay History report, click the Enable Project Commissions checkbox.
In the Projected Template Names field, enter the template names/revisions which should be included in projected commissions.
Adding Rank Values to the Database
In the process of creating your compensation plan, you defined
<rules> that resulted in your ranks.
<Rule Name="Gold" Description="Gold level rank"> <And> <MeetsRule Rule="Silver" /> </And> <Result> <SetRank Rank="20" /> </Result> </Rule>
In order for these ranks to apply, you’ll have to manually add the rank names (e.g., Gold) and values (e.g., 20) to the CRM_Ranks table in the database using the Data Editor.
Step-by-step guide: How To Add Compensation Plan Rank Values to the Database Using the Data Editor