User Guide | PUBLIC

Document Version: PROD – 2025-03-28

Incentive Management Admin Design Guide

© 2025 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

1 SAP SuccessFactors Incentive Management on Hyperscalers . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 Incentive Management Admin Design Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3 Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

3.1 Accessing the Incentive Management Admin Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Workspace Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Customizing Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Summary and Detail Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
List View & Tree View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Custom Attributes and Reporting Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Menu Tabs and Related Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Data Loaders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Workspace Refresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
User Interface Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.3 Operation Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Selecting Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Expanding and Collapsing in Tree View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Data Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Disallowed Special Characters for all Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Editing Information - Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Copying and Deleting Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4 Overview: Periods, Dates, and Versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Specifying the Effective Dates of a New Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Viewing Audit History of an Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Object Versions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

4 Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.1 Simple Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
4.2 Advanced Search Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.3 Using Advanced Search Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.4 Using Advanced Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.5 Saving Advanced Search Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.6 Related Search Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

5 Organization Data Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

5.1 Participants Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.2 Titles Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Incentive Management Admin Design Guide

2 PUBLIC Content
5.3 Positions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.4 Position Assignments Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.5 Relationships Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using the Relationships Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

6 About Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.1 Plans Wizard Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6.2 Creating a Plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.3 Adding Rules to a Plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4 Plan Assignments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Assigning a Plan by Title. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Assigning a Plan to a Specific Position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.5 Editing a Plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.6 Deleting a Plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7 Finding Objects Related to Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.8 Plan Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Plan Components Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Creating a Plan Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Adding Rules to a Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Adding a Component to a Plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Editing a Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Deleting a Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Finding Objects Related to Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Audit History for Plan Component Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

7 About Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

7.1 Rules Wizard Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
7.2 Rule Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
7.3 Rule Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
7.4 Rule Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
7.5 Overview: Multiple Actions in Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Rule Actions: Reportable Flag and Display Name of Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.6 Overview: Editing a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Renaming a Compensation Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Deleting a Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
7.7 Finding Objects Related to Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
7.8 Overview: Generic Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Using Generic Attributes in Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Example: Generic Attributes on Credit Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
7.9 Multiple Actions In Rules: Implications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Implications of Inappropriate Multi-Actions Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
7.10 Rules that Produce the Same Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Incentive Management Admin Design Guide

Content PUBLIC 3
7.11 Rules in Compensation Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

8 Classification Data:Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

8.1 Classification Data Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
8.2 Categories Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
8.3 Classifiers Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
8.4 Working With Categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Creating a Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Moving a Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Deleting a Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
About Category Hierarchies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
8.5 Working With Classifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Creating a Classifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Editing Multiple Classifiers (Bulk Edit). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Deleting a Classifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Assigning a Classifier to a Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Versioning of a Classifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
About Classifier Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

9 Credit Eligibility Rules Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

9.1 Configuring Credit Eligibility Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139

10 Credit Rules Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

10.1 Input and Filters in Credit Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
10.2 Actions in Credit Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
10.3 Creating a Credit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Creating a Rolled Order Credit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Creating a Direct Order Credit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Creating a Rolled Transaction Credit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Creating a Direct Transaction Credit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

11 About Measurement Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

11.1 Creating Measurement Rules Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.2 Creating a Primary Measurement Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.3 Creating a Secondary Measurement Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

12 Incentive Rules Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

12.1 About Basic Incentive Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
12.2 Commission Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
12.3 Result Type and Filters in Incentive Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
12.4 Tiered Rate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
12.5 Straight Rate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
12.6 Creating an Incentive Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Incentive Management Admin Design Guide

4 PUBLIC Content
12.7 Creating a Commission Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .168

13 Deposit Rules Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

13.1 Input and Filters in Deposit Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
13.2 Deposit Rule Hold Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
13.3 Creating an Incentive-Based Deposit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
13.4 Creating a Detail Deposit Rule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

14 Formulas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
14.1 Formulas Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
14.2 Formula Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
14.3 Legal Moves Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Available Legal Moves. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Formatting Items in the Expression (Formula) Edit Pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
14.4 Using Legal Moves Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Specifying Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Specifying Listed and Unlisted Data Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Specifying References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Specifying Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
How Input to Formulas Determines Range of Use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
14.5 Referencing Measurements and Incentives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Referencing an Incentive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Referencing a Measurement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
14.6 Creating a Formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
14.7 Editing a Formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
14.8 Deleting a Formula. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
14.9 Finding Objects Related to Formulas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

15 About Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197

15.1 Variable Assignments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
15.2 Variable Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
15.3 Creating Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Creating a Fixed Value Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Creating a Rate Table Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Creating a Territory Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Creating a Lookup Table Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
15.4 Editing Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
15.5 Deleting a Variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
15.6 Finding Objects Related to Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
15.7 Assigning Rule Elements Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
Assigning or Removing a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
Assigning or Removing a Territory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Incentive Management Admin Design Guide

Content PUBLIC 5
 Assigning or Removing a Rate Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Assigning or Removing a Fixed Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

16 About Territories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210

16.1 Territory Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
16.2 Creating a Territory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
16.3 Editing a Territory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
16.4 Deleting a Territory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
16.5 Finding Objects Related to Territories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

17 Fixed Values Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

17.1 Fixed Values and Effective Dates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
17.2 Using a Fixed Value or Quota. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
17.3 Fixed Values and Quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
17.4 Fixed Values Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
17.5 Creating a Fixed Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
17.6 Editing a Fixed Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
17.7 Deleting a Fixed Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
17.8 Finding Objects Related to Fixed Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

18 Quotas Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

18.1 Quotas Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
18.2 Creating a Quota. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
18.3 Editing a Quota. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
18.4 Deleting a Quota. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
18.5 Finding Objects Related to Quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
18.6 Quota Functions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Sum Subordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Sum Leaf Subordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Distribute to Subordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Distribute to Leaf Subordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Sum Sub-Periods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Distribute to Sub-Periods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Distribute to Leaf Sub-Periods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

19 About Rate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

19.1 Rate Table Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
19.2 Creating a Rate Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Creating a Rate Table that Handles Negative Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
19.3 Editing a Rate Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
19.4 Deleting a Rate Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
19.5 Finding Objects Related to Rate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

20 About Lookup Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Incentive Management Admin Design Guide

6 PUBLIC Content
20.1 About Dimension Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
20.2 Lookup Tables Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
20.3 Best Practices for Using Lookup Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
20.4 Restrictions Involved in Lookup Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
20.5 Options for Cell Values in a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
20.6 Building a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
Adding a Dimension to a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Removing a Dimension from a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Removing an Index from a Lookup Table’s Dimension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Editing Cells in a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .244
Entering a Fixed Value Variable in a Lookup Table Cell. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Entering Formulas and Expressions in a Lookup Table Cell. . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
20.7 Creating a Reference to a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Referring to Lookup Tables with Category Dimensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
20.8 Editing a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
20.9 Deleting a Lookup Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
20.10 Finding Objects Related to Lookup Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

21 About Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

21.1 Primary Functions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Absolute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Calculate Result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252
Concatenate Two Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Convert Boolean to Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Convert Null to Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Convert String to Upper Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Convert String to Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Convert Value to Boolean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Current Period. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Equals (Ignore Case). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Is Null and IsDateNull. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Is In Range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Max and Min. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Other Position’s Quota or Fixed Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Participant.Version() and Position.Version() Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Round. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Set Unit Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
Transaction.Payee Pre-Assignment () Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Transaction.Classifier(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Position.Has Accepted Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Trim String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Trunc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Incentive Management Admin Design Guide

Content PUBLIC 7
21.2 Sum Functions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Sum Prior Quotas or Fixed Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Sum Prior Measurements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Sum Measurements to Date by Participant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
Sum Prior Measurements by Participant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Sum Prior Incentives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Sum Incentives to Date by Participant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Sum Prior Incentives by Participant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Sum Quotas or Fixed Values to Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Sum Measurements to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Sum Incentives to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Sum Deposits to Date and Sum Deposits to Date with Status. . . . . . . . . . . . . . . . . . . . . . . . . . 272
21.3 About Order-Level Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Credit.Is Order Credit() and Source Credit.Is Order Credit(). . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Order Max/Min Credit - DO/RO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Order Max/Min Transaction - DO/RO/DC/RC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Order Sum Credits - DO/RO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Order Sum Transaction Units - DO/RO/DC/RC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Order Sum Transactions - DO/RO/DC/RC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Order Num Transactions - DO/RO/DC/RC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Transaction Line and Order Total() Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
21.4 Text Search Functions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
String Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
String Ends With. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
String Starts With. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Substring Between. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
Substring From. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Substring Using Pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
21.5 Date Functions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
About Date Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Add Time to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Calendar Start Date and Calendar End Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Convert Date to String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Convert Number to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Convert String to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Fiscal Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Fiscal Period Start Date and Fiscal Period End Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Measure Time Between Dates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Measure Time Overlap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Measure Time Overlap Percentage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Measure Periods Between Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288

Incentive Management Admin Design Guide

8 PUBLIC Content
 Measure Period Overlap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Measure Period Overlap Percentage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Calculation Run Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
21.6 Ranking Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Rank By Measurement () and Rank By Incentive () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Total Population for Ranked Measurement () and Total Population for Ranked Incentive ()
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
21.7 Position Proration Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Participant Proration Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
21.8 Query Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Query for Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Query for String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Query for Boolean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Query for Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Example Usage: Query for Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Groovy Function for Custom Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305

22 Extending Product Functionality Using Query Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

23 Calculations Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

23.1 Orders, Transactions, and Credits in Tree View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
23.2 About Orders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
Orders Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Creating an Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Finding Transactions and Credits Related to Orders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
23.3 About Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Transactions Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Creating a Manual Transaction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Specifying Payee Pre-Assignments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
Modifying Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Removing a Payee Pre-Assignment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Adjusting Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Copying Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
Finding Objects Related to Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
23.4 Credits Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Credits Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
Creating a Manual Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Transferring Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
Modifying a Credit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Adjusting Credits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Copying Credits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Setting a Credit’s Release Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Incentive Management Admin Design Guide

Content PUBLIC 9
 Finding Objects Related to Credits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
23.5 Measurements Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Measurements Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Finding Objects Related to Measurements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
23.6 Incentives Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Incentives Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333
Finding Objects Related to Incentives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
23.7 Commissions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Commissions Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Finding Objects Related to Commissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
23.8 About Deposits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Deposits Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Adjusting Deposits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Modifying a Deposit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

24 Payments and Balances Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

24.1 Payments Workspace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
24.2 Negative Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
24.3 Grouping and Balancing Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
Earning Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Earning Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Multiple Currencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
24.4 Earning Code Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
24.5 Consolidating Payee Payments Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Enabling Payee Payment Consolidation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
About Payee Payment Consolidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

25 Deletion Policies Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

25.1 Deleting Reference Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
25.2 Deleting Administrative Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

26 References to Measurements and Incentives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

26.1 Primary Measurements Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
References to Synthetic Versions of Primary Measurements. . . . . . . . . . . . . . . . . . . . . . . . . . 362
26.2 Secondary Measurements and Incentives Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Persistent and Synthetic Versions of Measurements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Persistent and Synthetic Versions of Incentives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
References to Measurements and Incentives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Issues with References to Secondary Measurements and Incentives. . . . . . . . . . . . . . . . . . . . . 365
26.3 Self-Referencing Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
26.4 Synthetic Values and Sum Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
26.5 Period Type Parameters and Rate Tables Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368

Incentive Management Admin Design Guide

10 PUBLIC Content
 Period Type Parameter Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
26.6 Using Period-Based Versions of Measurements and Incentives Summary Guidelines. . . . . . . . . . . .370

27 Modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
27.1 Modeling Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
27.2 Creating and Running Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Adjusting Rate Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Adjusting Fixed Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
27.3 Model Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
27.4 Model Run Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
27.5 Viewing Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
27.6 Using Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382

28 Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
28.1 Integration with SAP S/4HANA Cloud and S/4HANA Private Cloud. . . . . . . . . . . . . . . . . . . . . . . . 384
Integration Flow Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
System Preparation for Data Replication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Timer Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Receiver Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
More Options (Partner Functions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
Deploying the Integration Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Logging and Monitoring Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .402
Error and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Email Notification Flow Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
Difference Between SAP S/4HANA and SAP SuccessFactors Incentive Management Data
Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Integration with SAP S/4HANA Cloud and S/4HANA Private Cloud - Glossary. . . . . . . . . . . . . . 407
28.2 Integration with SAP IdP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Bottom-Up User Synchronization with Identity Authentication . . . . . . . . . . . . . . . . . . . . . . . . 409
Top-Down User Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
About Identity Provisioning and Identity Authentication SSO Integration for SAP
SuccessFactors Incentive Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .439
Renewing SAML Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
28.3 Integration with SAP Business Technology Platform (BTP). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Default Catalogs for Automation Pilot and Alert Notification Service. . . . . . . . . . . . . . . . . . . . . 447
Importing the Default Catalog for SAP Alert Notification Service. . . . . . . . . . . . . . . . . . . . . . . 448
Importing the Default Core Catalog for SAP SuccessFactors Incentive Management . . . . . . . . . 451
Importing the Default Tenant Specific Catalog for SAP SuccessFactors Incentive Management
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Automation Pilot Core Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Automation Pilot Tenant Specific Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483
Smart Detection Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Commands for Running Data Sphere Task Chains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .496

Incentive Management Admin Design Guide

Content PUBLIC 11
 SAP Automation Pilot Integration: Downloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
28.4 Integration with SAP Data Custodian. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
28.5 API Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Service Account Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
User Authentication Using JWT token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

29 Data Integration and Management Solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522

30 Downloading SAP HANA Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

31 Known Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527

31.1 Known Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527

Incentive Management Admin Design Guide

12 PUBLIC Content
1 SAP SuccessFactors Incentive
Management on Hyperscalers

SAP SuccessFactors Incentive Management on Hyperscalers is a cloud-native solution built on a microservices

architecture that leverages the Kubernetes (K8s) platform. K8s architecture is an open-source container
orchestration system for scaling, and managing containerized applications, which is a new way to design and
develop. It simplifies operations, brings down costs, and deploys innovations faster.

With this enhanced backend technology,SAP SuccessFactors Incentive Managements gains superior speed,
concurrency, scalability, and performance, helping you achieve lower downtime and higher availability. Splitting
the backend into microservices results in better performance throughout the SAP SuccessFactors Incentive
Management application.

Here are some enhanced capabilities available on the microservices architecture:

• Zero downtime releases and maintenance assure no interruption in your business while enhancing the
application to bring more value to you. It also assures the next level of agility when your business requires
it.
• Ability to monitor each service, isolate and resolve issues quickly while maintaining maximum system
uptime in other areas. For e.g., if the email service is down, no emails can be sent, but the rest of the
system can be used.
• Enhanced application UI load time provides for an immediate improvement in User Experience and
efficiency of work.

This infrastructure modernization supports the expansion of the SAP Business Technology Platform across the
entire portfolio and provides a future-proof foundation for your business and people transformation.

Incentive Management Admin Design Guide

SAP SuccessFactors Incentive Management on Hyperscalers PUBLIC 13
2 Incentive Management Admin Design
Guide

Learn about configuring workspaces, organization data, compensation plans, rules, calculations, and more.

Quick Start Guide

• Getting Started [page 15]

• Workspace Basics [page 18]
• Search [page 49]
• Organization Data [page 59]
• About Incentives [page 333]
• Plans [page 87]

Incentive Management Admin Design Guide

14 PUBLIC Incentive Management Admin Design Guide
3 Getting Started

The administrator creates users and assigns them with the security roles that govern their access to different
operations. The administrator must provide users with a user account that includes a username and password.
The security role and its permission settings influence what users can and can’t access and what actions can or
can’t be performed. Furthermore, if business units are implemented, users can only access objects that belong
to those business units to which the user is assigned. See the Incentive Management Admin Tasks Guide for
more information about security roles, permissions, and access to business units.

Related Articles

• Accessing the Incentive Management Admin Application [page 15]

• Customizing the Display [page 19]
• Workspace Basics [page 18]
• Operation Basics [page 35]
• Periods, Dates, and Versions [page 43]

3.1 Accessing the Incentive Management Admin

Application
Before you begin, contact your administrator to set your username, password, security role, access rights,
security permission settings, and business unit access.

Procedure

1. In the Apps drop-down, choose Incentive Management Admin.

Incentive Management Admin Design Guide

Getting Started PUBLIC 15
2. The Incentive Management Admin home page is displayed. If this is your first login, the system opens the
first period of the main monthly calendar. You can reset it to another period on the current calendar, a
period on a different calendar, or a specific date using the Calendar field.

Choose the Sign Out option from the user profile to sign out of the system.

Setting Up the Default Period

When you sign in to the system for the first time, the Default Period is set based on the Main monthly calendar.

When you specify a period for your default period, only those objects that are effective as of the last day of
that period are displayed. For example, if your period is July 2008, and there are three versions of a position
effective during that month—July 1 through July 10, July 11 to July 20, and July 21 to EOT—only the last version
(July 21 to EOT) is displayed. To see the other versions that are effective during July, you can use the Manage
Version icon to view, and modify other versions if necessary. As an alternative, you can also specify a specific
date for the default period.

 Note

If you specify a period for your default period, objects that have been end-dated in that period are displayed
even though they are not current as of the last day of the period. For example, if the period specified is July
2008, all objects with effective end dates between July 1 and July 30 are displayed.

Perform the following steps to specify a default period:

1. The Default Period is displayed on the top-right of the application. Choose Calendar next to the Default
Period.
2. Select a calendar from the Select Default Period dialog.
3. Select the Period or search from the auto-populated search bar.

Incentive Management Admin Design Guide

16 PUBLIC Getting Started
4. Choose the Date option and set the date.

5. Choose Apply.

 Note

If a period is selected, the name of the period displays in the Default Period field. If you specify a date, that
date displays in the Default Period field. The Calendars and periods displayed depend on what calendars
have been set up by the administrator.

Alternatively, you can use the Set my default view period to preference in Manage Setup > Preferences >
User Preferences to determine the default period that should be used on subsequent sign-ins.

Related Information

Workspace Basics [page 18]

Incentive Management Admin Design Guide

Getting Started PUBLIC 17
3.2 Workspace Basics

Related compensation tasks are grouped into workspaces.

Application elements:

General application elements in the header include:

• Application Menu: From the application menu, you can navigate to related components and integrated
applications. The available applications might vary depending on what products are installed.
• Profile: Enables you to select the user account you want to Proxy As, configure your profile settings, and
sign out of the application .
• Help: Provides links to the application help content and other resources.
• Feedback: Enables you to provide your feedback about the Incentive Management solution. The brief
1-minute survey is anonymous and does not collect personal data. Please refrain from sharing any personal
information in your feedback.

Navigation and display elements:

• Left Menu Options: Helps you to navigate through workspaces.

• Workspace Toolbar: Contains icons to enable actions and configure the display.
• Workspace Summary and Detail View: See Summary and Detail Views [page 20] for details.

Search Options:

The system provides you with the following search options depending on the workspace:

• Simple search: Provides access to the simple text-based search functionality.

• Advanced search: Provides the ability to search by specific fields or construct SQL like queries. See Search
[page 49] for details.

Related Information

Customizing Display [page 19]

Summary and Detail Views [page 20]
List View & Tree View [page 21]
Custom Attributes and Reporting Attributes [page 22]
Menu Tabs and Related Workspaces [page 24]
Data Loaders [page 29]
Workspace Refresh [page 31]
User Interface Elements [page 32]

Incentive Management Admin Design Guide

18 PUBLIC Getting Started
3.2.1 Customizing Display

You can customize the display of some UI aspects:

• Change the order in which columns display

• Change object and attribute names in workspaces
• Change the sort order of information in columns
• Resize some windows and dialogs

Changing the Column Display

This section contains a summarized view of the record. You can add or remove columns to the summarized
view using the Configure Summary View option in the toolbar. Here's an illustration of the configuration.

In the Configure Summary View popup, you can add or remove columns from Available Fields and Current Fields
using the drag-drop method. However, mandatory fields cannot be deselected from the Current fields section.

Changing Object and Attribute Names in Workspaces

If you have appropriate security access, you can customize names of objects and object attributes in the
Customization workspace.

Incentive Management Admin Design Guide

Getting Started PUBLIC 19
Changing the Column Information Sort Order

In the summary view, you can change the sort priority and order the columns. If the information was sorted
when the original search was done, the sort indicator arrow indicates whether the sort was ascending (an up
arrow) or descending (a down arrow). You can choose a column label to re-sort that column and change its sort
priority to primary. If a column was not included in the original sort priority, it can be added by clicking its label.
When a column is added, its sort priority defaults to primary, and the sort order defaults to ascending.

 Note

List attributes, such as business units, cannot be added to the sort priority. A list attribute is an attribute
that can have a single value, multiple values, or, in some instances, no (null) values.

Resize Dialogs and Windows

You can resize some dialogs and windows to display more data. For example, the Versions dialog can be resized
to display more fields. If you attempt to edit an object in the system that is being edited by another user, the
system displays a warning message: There are errors in your form. Please correct them before saving.

3.2.2 Summary and Detail Views

Many workspaces are divided into Summary View and Details View. The views are also referred to as the
'Summary panel' and 'Details panel' in the documentation.

The Summary View displays the list of records by default, allows you to access the details of a record, enables
users to perform actions on a selected record, and shows the object record count as well as the pagination
information. The checkbox option can be used only to select records to perform the actions available in the
toolbar. In several workspaces, you can view the summary in list view or tree view.

The following images illustrate the Summary View and Details View.

Incentive Management Admin Design Guide

20 PUBLIC Getting Started
The Details View displays the details of the selected record. To open the Details View, click on the arrow icon in
the first column, or anywhere in the row (except on data with links). If the data is linked, clicking the link opens
the related workspace.

You can view the data table and the details of the record in a side-by-side (split view) without losing context.

See Editing Information - Overview [page 38] for details.

Use the Configure Summary View and Configure Details View options to configure your display.

3.2.3 List View & Tree View

View As List

Certain workspaces give you different view options for viewing your summary data in a list or tree view. If a
workspace has a list view option, then the view defaults to list view when you first access that workspace. If you
subsequently select tree view, the workspace displays in the tree view the next time user access it during the
same working session.

Incentive Management Admin Design Guide

Getting Started PUBLIC 21
The list view displays data in a tabular format. These workspaces provide the list view:

Main Menu Workspace

Organization Participants, Positions, Titles, and Relationships

Classification When you enter information and Products, Customers,

Postal Codes, and workspaces associated with user-defined
classifier types

Plans Plans, Fixed Values, Formula, Rate Table, Territory, Variables,

Quotas, and Lookup Tables

Results Transactions, Credits, Measurements, Incentives, Deposits,

and Payments

Administrator Messages Logs

When you navigate to a workspace in list view for the first time during a session, the summary view populates
objects to fill the available window space. If you navigate away from the workspace and then return to it, the
results displayed are from the last time you accessed that workspace.

View As Tree

When you switch to tree view from the list view, the summary view populates objects to fill the available window
space. If you navigate away from the workspace and then return to it, the results displayed are from the last
time you accessed that workspace.

The tree view displays data in a tree structure that shows relevant data relationships. For example, in the
positions workspace, clicking the tree view displays the reporting hierarchy. The nodes in the tree structure can
be expanded and collapsed as needed.

These workspaces provide the tree view:

Control Tab Workspace

Organization Positions and Relationships

Administrator Calendars

3.2.4 Custom Attributes and Reporting Attributes

Custom Attributes

You can use custom attributes to enter additional information about objects. For example, in the Participants
workspace, you might use custom attributes to enter values for a participant’s street address and email
address. See Customizations for more information on setting up custom attributes.

Incentive Management Admin Design Guide

22 PUBLIC Getting Started
Custom attributes can be enabled for all the following workspaces:

• Participant
• Customer
• Credits
• Titles
• Postal Codes
• Measurements
• Positions
• Orders
• Incentives
• Products
• Transactions
• Deposits

You can add the enabled custom attributes to Summary or Details view by configuring the Summary view and
Details view. You can include data stored in the custom attributes in your compensation rules. For example, you
can include a custom attribute that stored a country code in a rule’s condition.

Here's an example of the custom attribute section in the Participants workspace:

Reporting Attributes

Reporting attributes are used only for reporting purposes. They cannot be used in compensation plan rules,
and therefore are not included in calculation processing. Reporting attributes can be enabled for the following
workspaces:

Reporting Attributes

Incentive Management Admin Design Guide

Getting Started PUBLIC 23
• Participant
• Positions
• Transactions

3.2.5 Menu Tabs and Related Workspaces

Each workspace provides you can access to specific objects. For example, from the Organization tab, you can
access organization related compensation data objects such as participants and positions using appropriate
workspace icons.

Your security role and its permission settings influence what you can and cannot access, and what actions you
can or cannot perform. If business units are implemented, you can only access objects that belong to those
business units to which you have been assigned.

 Note

You can find Compensation data within the Organization, Plans, and Classification tabs, which is also
known as reference data and includes information about positions, participants, position assignments,
compensation plans & rules, and rule elements (such as Territories, rate tables, and lookup tables).
Reference data must exist before you can run the calculation.

This section lists the available workspaces and summarizes the objects available to you in each workspace.

The following table describes the workspaces available in the Organization menu. This workspace handles
specific information about your company: participants, positions, specific job assignments, titles, reporting
relationships, and roll relationships. Organization data is often supplied by human resources and the imported
into the systems

Workspace Tasks

Participants: Workspace for participants in compensation • Create, edit, copy, and delete participants and partici-
plans. pant information.
• Search for participants
• Find related objects
• Data loaders

Positions: Workspace for defining the positions in your or- • Create, edit, copy, and delete positions and position in-
ganization. A position is a specific, unique job in a specific formation
area of the company. You can view positions as a reporting • Search for positions
hierarchy in the tree view.
• Assign plans to positions
• Find related objects
• Data loaders

Incentive Management Admin Design Guide

24 PUBLIC Getting Started
Workspace Tasks

Relationships: Describes a path for rolling credits from the • Create, edit, copy, and delete roll types and roll relation-
source position to receiving positions in that single roll path. ships
Roll relationships are assigned to a roll type. • Search for relationships and roll types
• Find related objects

Titles: Titles workspace for all job types in your organization. • Create, edit, copy, and delete titles
• Search for titles
• Assign plans to titles
• Find related objects
• Data loaders

The following table describe the workspaces available in the Plan Data menu. This workspace sets up the
variable compensation plans that determine how people in your organization are paid. Plans are typically
created when the system is implemented for the first time. You can also create new plans and modify existing
plans when required

Workspace Tasks

Plan Components: Components Workspace for creating • Create, edit, copy, and delete plan components.
plan components. The components are templates that con- • Assign components to plans.
tain a set of Rules.
• Distribute plan documents.

Plans Wizard: Workspace for creating compensation plans. • Create, edit, copy, and delete plans and plan informa-
Compensation plans contain compensation rules that typi- tion
cally correspond to the different stages of the process en- • Search for plans
gine, called the calculation. The wizard walks you through a
• Create, add, and remove rules associated with a plan
series of screens to set up rules.
• Find related objects

Rules Wizard: Workspace for compensation rules. Each rule • Create, edit, copy, and delete rules
type provides processing directions for the corresponding • Search for rules
calculation stage. Compensation rules in each plan work
• Find related objects
together to allocate credits, process compensation results,
and determine payments for participants who are assigned
to the plan. The wizard walks you through a series of screens
to set up rules.

Incentive Management Admin Design Guide

Getting Started PUBLIC 25
Workspace Tasks

Classification: Workspace for all categories and classifiers, Create, edit and delete category hierarchies, categories, and
used to filter transactions into groups based on specific
classifiers, including:
fields on each transaction. Classification workspace also in-
cludes workspaces for the pre-defined classifier types (Prod- • Add classifiers to categories
ucts, Customers, and Postal Codes), and any other workspa-
ces based on the classifier types defined by the administra-
• Remove classifier assignments
tor. • Move classifiers to different category hierarchies and
categories
Products: Workspace for Products categories. If your com-
pany allocates credits based on product information found in • Find related objects for category hierarchies, catego-
the transaction, you can use a category hierarchy with Prod- ries, and classifiers
uct classifiers to filter for transactions that contain specific • Data Loaders
product information.
Create, edit, copy, and delete product classifiers and product
Customer: Workspace for Customer categories. If your com- categories, including:
pany allocates credits based on customer information found
in the transaction, you can use a category hierarchy with
• Add product classifiers to product categories

customer classifiers to filter for transactions that contain • Remove product classifier assignments
specific customer information. • Search for product details

Postal Code: Workspace for postal codes categories. If your • Find related objects

company allocates credits based on postal codes found in • Data Loaders

the transaction, you can use a category hierarchy with postal
Create, edit, copy, and delete customer classifiers and cus-
code classifiers to filter for transactions that contain specific
tomer categories, including:
postal codes.
• Add customer classifiers to customer categories
• Remove customer classifier assignments
• Search for customer details
• Find related objects
• Data loaders

Create, edit, copy, and delete customer classifiers and cus-

tomer categories, including:

Add customer classifiers to customer categories

Remove customer classifier assignments

Search for customer details

Find related objects

Data loaders

Credit Eligibility Rules: The Credit Eligibility Rule workspace Create and mange CES rules.
is used to create Credit Eligibility Rules, which are used to
generate transaction pre-assignments by matching fields in
the Transaction with the Territory mapping (specified in Ge-
neric Classifier table).

The following table describe the workspaces available in the Compensation Elements menu.

Incentive Management Admin Design Guide

26 PUBLIC Getting Started
Workspace Tasks

Fixed Values: Workspace for fixed values, a value that can be • Create, edit, copy, and delete fixed values
used wherever a value is called for. • Search for fixed values
• Find related objects

Formulas: Workspace for formulas, user-defined mathemat- • Create, edit, copy, and delete formulas
ical expressions that produce calculated values. Formulas • Search for formulas
are used most often in conditions and action statements
• Find related objects
within a rule, but they can also be employed in rate tables
and lookup tables when a calculated value is required.

Lookup Tables: Workspace for lookup tables, n-dimensioned • Create, edit, and delete lookup tables
tables that store indexed values retrieved by rules and for- • Search for lookup tables
mulas.
• Find related objects

Quotas: Workspace for quotas, values that apply across an • Create, edit, and delete quotas
entire reporting structure. • Search for quotas
• Find related objects

Rate Table: Workspace for rate tables, tiered tables used • Create, edit, copy, and delete rate tables
in an incentive rule to calculate how much a position assign- • Search for rate tables
ment receives in commissions based on a step-commission
• Find related objects
rate.

Territories: Workspace for territories, the named combina- • Create, edit, copy, and delete territories
tion of categories and classifiers that filters input to credit • Search for territories
and measurement rules.
• Find related objects

Variables: Workspace for variables, the named placeholders • Create, edit, copy, and delete variables
used in rules to reference a rule element (such as a rate • Search for variables
table, territory, fixed value, or lookup table.)
• Find related objects

The following table briefly describes each of the workspaces available from the Plan Communicator menu.

Workspace Tasks

Distribution, Distribution TRacking, Documents, Disutes Create manage documents and distributions, raise disputes,
Tracking, Disputes configure Plan Communicator, and more.

The following table briefly describes each of the workspaces available from the Calculations menu. You can
run the pipeline in the Calculations workspace. You can view transaction data used as an input to calculation
runs and view results data that is based on compensation processing for each period. You typically run the
calculation to process compensation payments at least once a period.

Incentive Management Admin Design Guide

Getting Started PUBLIC 27
Workspace Tasks

Pipeline: Workspace for compensation processing, which in- • Run the calculation for any period or multiple periods at
cludes running calculations, importing data, purging data once
and other related tasks. The workspace shows execution • Run the calculation for specific stages
progress in real time. Optional profiling is available for any
• Schedule a calculation run
calculation run.
• Cancel a calculation run
• Search for calculation runs for any period
• Import data from the staging tables
• Import XML data
• Update analytics
• Purge data from the staging tables

Orders: Workspace for order- and transaction- level credit • Create, edit, view, copy, and delete orders
allocation results data. • Search for orders
• Find related objects
• Data loaders

Transactions: Workspace for transaction level credit alloca- • Create, edit, view, copy, and adjust the value of transac-
tion results data. Transactions are business events that drive tions
the compensation process. Transactions are the smallest • Search for transaction details
units of sales data. They are classified by categories, and
• Find related objects
credits are allocated to classified transactions.
• Data loaders

Credits: Workspace for credits allocation results data. Cred- • Create, edit, view, and copy credits; and transfer and
its are allocation values assigned to a position assignment. adjust the value of credits
Credits are allocated to either a sales transaction or to an • Search for credits
order (or parts of an order).
• Find related objects

Measurements: Workspace for measurement results data. • Search for and view measurements
Primary measurements aggregate the credits or other items • Find related objects
for position assignments. Typically, aggregating credits in-
volve summing the monetary value of credits. Secondary
measurements sum primary measurement values.

Incentives: Workspace for incentive results data. Incentives • Search for and view incentives
are the output of incentive rules, which compare measure- • Find related objects
ments or credits to quotas and rates.

Commissions: Workspace for Commissions, a kind of incen- • Search and view commissions to be paid
tive. • Find related objects

Deposit: Workspace for deposit results, which reflect incen- • Create, edit, view, and copy deposits
tives deposited for eventual payment. • Hold, release, and adjust deposits
• Find related objects

Incentive Management Admin Design Guide

28 PUBLIC Getting Started
Workspace Tasks

Payments: Workspace for payment and balance results. • Search for and view payments
• Find related objects

See the Administrative Tasks documentation for information on Global Values, Security, and Preferences.

3.2.6 Data Loaders

Upload Data

This option uploads data from an Excel worksheet template that matches the workspace columns and is
available in the following workspaces:

• Orders and Transactions workspaces for Results, Participants, and Positions.

• Titles workspaces for Organization
• Categories, Products, Customers, Postal Codes for Classification
• Calendars and Customization for Administration

To upload data, choose the Upload Excel Data option in the toolbar.

 Note

When uploading templates, you must ensure that the column header for numeric fields does not contain
more than one dot. For example, use PreAdjusted.UnitType for column header in the template. Do not
use PreAdjusted.Unit.Type

Download Template

This option is used to download either an empty template or all the data from the workspace to an Excel
worksheet. The downloaded Excel worksheet contains all the columns used in the workspace. This option is
available in:

• Orders and Transactions workspaces for Results, Participants, and Positions

• Titles workspaces for Organization
• Categories, Products, Customers, Postal Codes for Classification;
• Calendars and Customization for Administration

To download the template, choose the Download Template option in the toolbar.

 Note

Data loaders supports only Excel 2003 workbook format. For the best performance, do not use Data
Loaders for more than 1000 records per object.

Incentive Management Admin Design Guide

Getting Started PUBLIC 29
Export Data

This option exports data in Excel, CSV, or XML format as applicable. To export data, choose the Export Data
option in the toolbar.

The export feature is supported in the all the workspaces. The supported formats (CSV, Excel, or XML) and
specific steps vary depending on the workspace:

CSV Export:

1. Select Export Data from the Ellipsis Menu (…).

2. Choose CSV in Choose File Format.
3. Select the fields to export or use the default settings.
4. Specify the file settings to include or exclude the field name in the first row, specify text qualifiers, and
choose delimiters.
5. Export specific records, all displayed records, or specify ranges (up to 60,000 records per export).
6. Choose Export.

XML Export:

1. Select Export Data from the Ellipsis Menu (…).

2. Choose XML in Choose File Format.
3. Specify if all or only selected records must be exported.
4. Specify effective versions to export.
5. Select the related data to export.
6. Choose Export.

Incentive Management Admin Design Guide

30 PUBLIC Getting Started
Excel Export:

1. Select Export Data from the Ellipsis Menu (…).

2. Choose Excel in Choose File Format.
3. Export specific records, all displayed records, or specify ranges (up to 7000 records per export).
4. Choose Export.

3.2.7 Workspace Refresh

If an object in a workspace has been changed by a Calculation Run or by Import, you are notified that a refresh
should be done so that you are viewing or editing the most current version.

For example, if imported classifiers are part of a category you are viewing or editing in the Categories
workspace. The changes in the category for those classifiers are not displayed until the workspace in the
system is refreshed.

Incentive Management Admin Design Guide

Getting Started PUBLIC 31
The workspace refresh mechanism works as follows:

• If the current workspace is one of the workspaces affected by a calculation run or by import.
• If you are in the process of entering or modifying information, a Save dialog box is also displayed.
• If the current workspace is not one of the workspaces with updated objects, then no changes occur.
• Affected workspaces other than the current workspace are refreshed in the background. Updated data is
displayed the next time you access these workspaces.

3.2.8 User Interface Elements

The main workspaces and menu items are described in Menu Tabs and Related Workspaces [page 24].

The user interface elements are described below:

Toolbar

The toolbar is available on the top-right of the table in all the workspaces. The icons and action links available in
the toolbar enable you to perform workspace level tasks.

Primary actions such as Create, Search, and Related Search are available on the toolbar.

Other item specific actions (such as Edit, Delete, Audit etc.) and workspace specific actions (such as Import,
Export, Configure Summary View etc.) are grouped under the Ellipsis Menu (…).

The following table displays the toolbar icons and provides a brief description.

Incentive Management Admin Design Guide

32 PUBLIC Getting Started
Icon Description

Create Used to create a new Object

or

Search or Used to perform a name search or a simple text search by

entering keywords, depending on the workspace and active
view..

 Note
There is no search capability in the Customization work-
space.

Used for related search between objects. Advanced Related

Related Search or Search is provided within the Related Search. This option is
supported in Organization, Results, Rule, Rule Elements, and
Classification workspaces.

Advanced Search or Opens the Advanced Search section. You can perform an
Advanced Search by applying Filters and Sort Criteria.

Used to configure the columns in the Summary View. See

Configure Summary View or Summary and Detail Views [page 20] for details.

Used to configure the display in the Details View. See Sum-

mary and Detail Views [page 20] for details.
Configure Details View or

Used to delete one or more objects.

Delete or

Used to save information to the repository. The Save icon is

Save or not enabled until you actually make a change.

Used to return the display to its pre-edit state.

Cancel

Used to make a copy of a single object selected in the sum-

Duplicate or (Also, 'Copy' in some workspaces.) mary pane. The Duplicate option is enabled when objects are
selected in the summary pane. The Duplicate option is not
enabled in the Quotas and Lookup Tables workspaces.

Used to displays the audit history for a selected record.

Audit the Selected Object or

Used to Edit the current version, in the Details View. Also, it

is used to edit selected rows in Summary View (Bulk Edit).
Edit Version or

Incentive Management Admin Design Guide

Getting Started PUBLIC 33
Icon Description

Used to create a new Version of the selected object.

New Version or

This option is available in the Organization workspace. It

Research View or
launches the Research View workspace for the selected row.

This option is available in the Message Log workspace (list

Truncate or
view only). It opens the Truncate Message Log dialog, so that
entries prior to a specified date can be removed from the
log.

This option is provided in the Calculation workspace. It is

Run a Pipeline or used to cancel a selected run.

This option is available in the Orders and Transactions work-

Download Template or Data spaces for Results, and the Participants, Positions, and Titles
workspaces for Organization. It is used to download either
an empty template or the data for that workspace to an excel
worksheet with all the columns used in the workspace.

This option is available in the Orders and Transactions work-

Upload Excel Data or spaces for Results, and the Participants, Positions, and Titles
workspaces for Organization. . It is used to upload data con-
tained in an excel worksheet template matching the columns
used in the workspace.

In all supported workspaces, the export data option can be

Export Data or used to export data to either CSV, Excel, or XML format.

Apart from these, other keyboard shortcuts mentioned below helps you to perform tasks conveniently:

• Esc - Press Esc key to close the pop-up dialog.

Field Icons

The system provides several field-specific icons to assist you in creating new objects, modifying attributes of
current objects, and searching for objects.

Field Icons Operation

Used to display a calendar from which to choose dates.

Calendar or

Incentive Management Admin Design Guide

34 PUBLIC Getting Started
Field Icons Operation

Used to create new, inline objects. For example, if you are in

Create or
the Positions workspace, you can create a new title without
leaving the Positions workspace. It is also used to create
new versions of objects from the Versions for. In the Lookup
Tables workspace, it is used to add dimensions to lookup
tables, as well as to create new dimensions within a table.

Used in Versions to delete versions and in the Lookup Table

Delete or
workspace to delete dimensions and dimension indexes.

Expression
Provided in the Lookup table and Rate table. The Expression
icon to open Legal move editor dialog.

Literal or
The Simple/ Literal icon enables users to enter literal value.

Used to open the Legal Move editor dialog to view in ex-

panded mode.
Legal Move Editor or

3.3 Operation Basics

Learn about the various operations you can perform across many workspaces, for example, object selection,
deletion, copy, edit, and data validation.

Related Articles

• Selecting Objects [page 35]

• Expanding and Collapsing in Tree View [page 36]
• Data Validation [page 36]
• Disallowed Special Characters [page 37]
• Editing Information [page 38]
• Copying and Deleting Objects [page 41]

3.3.1 Selecting Objects

Incentive Management Admin Design Guide

Getting Started PUBLIC 35
No table record is pre-selected by default when a page loads.

In the Summary View, the checkbox option can be used only to select records to perform the actions available
in the toolbar. When one or multiple records are selected, the (bulk) edit action, as other applicable actions are
available.

To open the Details View, click on the arrow icon in the first column, or anywhere in the row (except on data with
links) . If the data is linked, clicking the link opens the related workspace.

You can see the total number of objects in the page footer along with the navigation buttons.

After you select a record, you can edit, delete, and export as single or multiple objects simultaneously.

You can select up to 250 objects at a time.

See Summary and Detail Views [page 20] for details.

3.3.2 Expanding and Collapsing in Tree View

In the tree view, use the arrow buttons to expand or collapse the Summary View.

3.3.3 Data Validation

Mandatory fields are outlined and marked as required.

To save an object, the required fields must be filled with valid entries.

If there is an error on the form the fields are outlined and an error message is displayed on top of the form by
listing errors in the following conditions:

• Required fields
• Incomplete values
• Incorrect or invalid values

Incentive Management Admin Design Guide

36 PUBLIC Getting Started
3.3.4 Disallowed Special Characters for all Names
The below characters are the standard set of disallowed special characters for names including object and file
names:

• ? (question mark)
• & (ampersand)
• ; (semi-colon)
• * (asterisk)
• < (less than)
• > (greater than)
• " (double quote)
• ‘ (apostrophe) (This is allowed in the participants workspace)

Use of these characters is discouraged due to problems in interaction with other products, but the system only
validates these characters in the following Participant's fields: First Name, Last Name, and User Name. If you
enter any of the characters into these fields, an error message is displayed. If you copy text in the process
of creating and modifying objects, use an ASCII text editor such as Notepad. Other word processing software
packages such as Microsoft Word usees different ASCII values for various fonts and character styles and the
value stored in the database might not be the same as the value displayed on the screen.

 Note

& (ampersand) can be used only for User IDs. For example, & (ampersand) can be used only for Participant
User ID, but not for Participant First Name, Last Name, and so on.

Exceptions to Name Character Rules

In addition to the disallowed characters, the following character cannot be used in Position group names (due
to calculation restrictions):

• , (comma)

Because the following special characters can cause potential access problems while viewing reports, it is
recommended not to use these in Position or Participant names in the system as well as in the user IDs
created:

• . (period)
• ; (semi-colon)
• / (forward slash)
• \ (backward
• # (pound)

Disallowed Special Characters for Function Parameters

The following characters cannot be used in Function parameters (strings and literal strings)

Incentive Management Admin Design Guide

Getting Started PUBLIC 37
• [ (left square bracket)
• ] (right square bracket)
• ( (left parenthesis)
• ) (right parenthesis)
• * (asterisk)
• | (pipe)
• ? (question mark)
• + (plus or addition sign)
• \ (backward slash)

Functions affected include:

• Concatenate Two Strings

• Convert String to Date
• Convert String to Upper Case
• Convert String to Value
• Equals (Ignore Case)
• Is Null
• String Contains
• String Ends With
• String Starts With
• Substring Between
• Substring From
• Substring Using Pattern
• Trim String

3.3.5 Editing Information - Overview

If your security role provides with the Update permission to a workspace, you can edit information for those
objects in that workspace in the Details view panel. See Summary and Detail Views [page 20] for details.

Keyboard Shortcuts

• Tab - The Tab key helps navigation forward within expressions (or form element)
• Shift + Tab -The Shift + Tab combination should bring navigation to the prior field (or expression or
form element) on the Form
• To check/uncheck a checkbox - press the Spacebar key
• To navigate to radio icon selection - press the Up arrow or Down arrow keys
• For new placeholder in Legal Move - press the Enter key
• Double click a Formula - When you double-click a formula in LME, the formula should pop up in the
Manage Versions form. Edits to the formula (name, effective version, logic, etc) will be saved.

Incentive Management Admin Design Guide

38 PUBLIC Getting Started
Editing a Version of the Object

When you edit an object, you are editing the current version of that object. If you need to edit a different
version, choose Manage Version and then select the correct version you want to edit. If the current version of
the object should remain the same, you can use the Create Version option to create a new object with new
information.

To edit information, perform the following steps:

1. Search for the object that needs to be updated.

2. Click on the arrow icon in the first column to open the record in Details View.
3. Choose Edit in Details View.
4. Make your changes.
5. Choose Save.

For more information about editing specific objects, see the related help documentation.

Bulk Editing Objects

You can select and edit multiple objects simultaneously. This is commonly referred to as bulk editing. It is
disabled if a field is unavailable for bulk edit. For example, you cannot bulk edit the Participant ID for multiple
participants. The following procedure discusses two different types of bulk editing

 Note

Editing Business Unit is not supported on any object.

Bulk Edit Objects in Organization, Classification, Results, and Stage Tables

1. Search for the object that needs to be updated.

2. Select the corresponding checkboxes to multi-select the objects in the Summary View.
3. Choose Edit Selected from the Ellipsis Menu (…) in the toolbar.
4. Select the field name to display the value column with the existing value. If multiple records are selected
the value displayed as various
5. Review the updates by selecting Summary.
6. Choose Update to save the changes.
7. Choose Acknowledge.

Bulk Edit Objects in Rule, Rule Elements, and Administration

1. Search for the object that needs to be updated.

2. Select the corresponding checkboxes to multi-select the objects in the Summary View.

Incentive Management Admin Design Guide

Getting Started PUBLIC 39
3. Select the appropriate object and edit the required information in the details panel.
4. Choose Save.

 Note

For example, to change the base salary for For example, to change the base salary for several participants
from $60,000 to $70,000, you could search for several participants from $60,000 to $70,000, you could
search for and select all participants earning $60,000 and update their new and select all participants
earning $60,000 and update their new base salary to $70,000 in a single step. All changes are For example,
to change the base salary for immediately reflected in the summary pane For example, to change the
base salary for several participants from $60,000 to $70,000, you could search for several participants
from $60,000 to $70,000, you could search for immediately reflected in the summary pane and select all
participants earning $60,000 and update their new

Viewing and Editing Related Objects

In workspaces that display the Formula, in edit mode, you can double-click the name of the related formula
object to bring up the Versions for Object dialog for that object. (This is the same dialog that displays when you
use the Edit Version button.) From this dialog, you can edit the object as required.

Edit a Related Formula Object

1. Navigate to the Rules Wizard workspace, and select a rule that refers to a formula.
2. Choose Edit.

3. Make changes as needed.

4. Choose Apply to save the changes to that object.

Saving or Reverting Changes

At any point, you can save your changes to the repository by selecting the Save button. Prior to saving, you can
return the workspace to its pre-edit state by choosing the Cancel option in the details panel. Choosing Cancel
displays a warning dialog. Choose Yes to continue. Choose No to remain in the edit mode.

Incentive Management Admin Design Guide

40 PUBLIC Getting Started
Changing the Business Unit of an Object

the assignment is disallowed. You can only select business units to which you as a user have been assigned.
You also cannot change the business unit of an object if it has associated results. You can, however, create a
new version of the object and assign a new business unit to it.

 Note

is assigned to a title, but the EMEA business unit is not assigned You must have the assign permission to
update business units.

Editing the Business Unit of an Object

1. Search for an object in the applicable workspace.

2. Click on the arrow icon in the first column to open the record in Details View.
3. Choose Edit in the Details View.
4. Choose the Edit Business Unit(s) from the details panel.
The displays the Change Business Unit for Object dialog.
• If the new business unit has not changed and the validate button is clicked, “No Change” is displayed,
this indicates that a business unit has not been selected.
• Because you can only assign one business unit to positions and position groups, there is no multiple
selections of business units in the Assign or Change the existing business unit drop-down. The
business units you select for positions and position groups must belong to the same processing unit.
• If the change is not allowed, the Change Business Unit for Object window displays the message “No
Business Unit interaction exists between selected object and referred by/referring to objects” in “This
record” table the column “Change Allowed” displays ‘No’ and the tables referred to or referred by
determining why the change was disallowed. In this case, you cannot save the change; you can only
cancel.
• If the change is allowed, the New Business Unit column displays the new business unit or business
units.
5. Select one or more business units from the Assign or Change the existing business unit drop-down and
choose Validate.
6. Choose Save if the change is allowed.

3.3.6 Copying and Deleting Objects

You can use the Copy option in the Summary View to copy an object or duplicate the same. The Copy option is
normally enabled when an object is selected in the Summary View. You can only copy one object at a time.

You can Delete reference data objects (organization data, classification data, plan data and rule elements) that
you have created either manually or through import. For example, if you have just imported or created both
participant and a position assignment that references that participant, you can delete the position. In this case,
the participant is disassociated from the position before the participant is deleted. In many instances, deleting
an object is disallowed. For example, you cannot delete reference data objects that are associated with results

Incentive Management Admin Design Guide

Getting Started PUBLIC 41
data. In instances where deleting an object is disallowed, you can instead end date the object. End dating an
object involves changing the end date on the last version of the object to a specific date. After this date, the
object is no longerconsidered active but remains in the repository.

Copying Objects

1. Search for an object.

2. Select that object in the Summary View.
3. Choose Duplicate in the Ellipsis Menu (…).
4. Specify the effective dates for the new object and then choose Ok. The new object displays with the same
name preceded by the words Copy of.
5. Edit the copied information as needed.
6. Choose Save.

 Note

As a best practice, it is recommended to attach plans to positions and then duplicate the position. This way,
all the plan information attached to the position is copied to the duplicated position, which is then attached
to the participant. Copying a participant doesn't copy the related position, so the plan information is not
attached to the copied participant. You need to modify the user ID, as each participant must have a unique
one. When duplicating compensation plans, the system checks for plans with the same name within the
same period and does not allow them to be saved.

 Note

The Copy icon is not enabled in the Quotas and Lookup Tables workspaces or in the Import views of any
workspace.

Deleting Objects

1. Search for an object or objects that you want to delete. You can bulk delete items by selecting multiple
objects at one time. The maximum number of objects that can be deleted simultaneously is 250.
2. Choose Delete.
3. Choose Yes to confirm the deletion.

 Note

Deleting an object removes all versions of the object from the repository. However, the audit log in the Audit
Log workspace retains information on the actions performed on that object, including its remove (delete)
date, and information about the object itself.

 Note

If the Prompt me before a record is deleted preference is enabled, then the Are You Sure? confirmation
dialog displays. If the Prompt me before a record is deleted preference is disabled or you disable

Incentive Management Admin Design Guide

42 PUBLIC Getting Started
 the Prompt me before a record is deleted option in the confirmation dialog earlier in your session, the
participant or participants selected are deleted immediately.

3.4 Overview: Periods, Dates, and Versions

The Effective Date range of a version of an object is determined by the start and end dates of that version. The
effective date is used to track which version of an object and its related objects are active in the system. The
objects are tracked by effective date include all reference data (organization data, classification data, plan date,
and rule elements). Effective dates are one of three ways that the sytstem tracks objects, the other ways are
audit date and calculation run date.

Related Articles

• Specifying the Effective Dates of a New Object [page 43]

• Viewing the Audit History of an Object [page 44]
• Handling Object Versions [page 45]

3.4.1 Specifying the Effective Dates of a New Object

When you create new objects, you are in essence creating the first version of that object. If necessary, you can
create new, additional versions of the object. Creating new object versions retains the old versions for auditing
purposes. In most workspaces, a Please Choose an Effective Start and End Date dialog displays when you are
creating an object. However, some objects, such as position groups and quotas, are internally effective dated
from the beginning of time (BOT) to end of time (EOT), and therefore a New Effective Start and End Date dialog
does not display. The New Object dialog also does not display for roll types. The BOT constant is 1/1/1900. The
EOT constant is 1/1/2200.

For some objects, the New Effective Start and End Date dialog contains a calendar field.

In general, plan data objects (plans and rules) and most rule element objects (formulas, variables, fixed
values, rate tables, and lookup tables) are associated with calendars. Organization data (participants, titles,
and positions) and classification data (category hierarchies, categories, and classifiers) are not associated with
calendars, and the calendar field is not displayed.

 Note

If you do not specify an effective end date for an object, the effective from date is derived based on the
default period and the effective date is set to EOT.

If necessary, select a calendar from the Calendar drop-down. The calendar associated with the default period is
displayed as the default. Click OK to accept this calendar and the default effective dates. The default calendar

Incentive Management Admin Design Guide

Getting Started PUBLIC 43
is the main monthly calendar. The calendar or calendars available depend on whether the administrator has
created additional calendars.

Procedure

1. Select a period
• You can only select a monthly period that is associated with the calendar selected. For example, if the
main monthly calendar was selected, you can only select a month within that calendar.
• If the default calendar is set to date, the effective from date defaults based on that date. For example, if
the default calendar is set to 01/15/2008, the effective from date defaults to January 2008.
2. Select a period from Through.
3. Choose Ok.
You can only select a monthly period that is associated with the calendar selected or end of time.

 Note

If you select a calendar other than the one associated with the default period, the object might not be
displayed when you save. Only objects associated with the default period are automatically displayed.

To specify new effective from and through dates, do one of the following:
4. Select an option . You can select a period that is associated with the current default period calendar or you
can use Select a date.
5. Select an option from Through.
6. You can select a period that is associated with the current default period calendar, use Select a date, or
select End Of Time.
7. Choose Ok.

3.4.2 Viewing Audit History of an Object

You can view the history of changes made to an object over time. Objects that are tracked by audit history have
an Audit History option in the respective workspaces.

You cannot view changes to quota values or lookup table values using Audit History from the Quotas
and Lookup Tables workspaces. To view changes to these values, use the Audit Log workspace. See the
Administrative Tasks documentation for more information on audit history and auditable objects.

Procedure

1. Select an object in the Summary View to view the audit history for that object.
2. Choose Audit History from the Ellipsis Menu (…) to view the details.

You can also use the Audit Log workspace to track additions, modifications, and deletions of objects. The Audit
Log also records when each user logs in or out of the system.

Incentive Management Admin Design Guide

44 PUBLIC Getting Started
3.4.3 Object Versions Overview

In the Versions workspace, you can create new versions and edit existing versions using the Manage Version
option for most effective dated objects.

 Note

Because versions are handled differently for position groups, relationships, quotas, and lookup tables,
these workspaces do not have the Manage Version icon. Also, period-based fixed values also do not have
the version icon.

Creating a New Version of an Object

You should create a new version of an object if the change you are making is newly effective and effective over
a span of time. Creating a new version also retains the old versions for auditing purposes. Retaining the old
versions makes it possible to track what version was effective at a particular point in time. For example, if a
participant’s salary changes, you would create a new version that reflects this change, but keep the old version
showing the participant’s previous salary.

 Note

If you have multiple versions of an object and you need to have just one version that replaces some or all of
those multiple versions, for performance reasons it is faster to create a new version with the new effective
date range. This is compared to editing an existing version of the object such that you extend the date
range of that existing version.

1. To create a new version of an object, search for an object for which you want to create a new version.
2. Select that object in the Summary View.
3. Choose Manage Version from the Ellipsis Menu (…) to view the Edit Versions dialog.
4. Choose Add to create a new version.
• If the default period is set to a period, the effective from date defaults based on that period, and the
through date defaults to end of time. For example, if the default period is set to January 2008, the
effective from date defaults to January 2008 and the through date default
• If the default period is set to a date, the effective from date defaults based on that date. For example, if
the default period is set to 01/15/2008, the Effective From date defaults to January 2008. If the object
is calendar based and the default date is outside the calendar, the Effective From date is blank and
must be specified. The through date defaults to end of time.
5. Enter effective dates for the new version using one of the following methods:
• Enter and select an option from the effective From auto search drop-down. If the object you are
creating a new version for is associated with a calendar, you can only select a period that is associated
with that calendar. If the object you are creating a new version for is not associated with a calendar, you
can select a period that is associated with the default calendar or use select a date to specify a date.
• Select an option from the through auto search drop-down. If the object you are creating a new version
for is associated with a calendar, you can only select a period that is associated with that calendar or
select end of time. If the object you are creating a new version for is not associated with a calendar, you
can select a period that is associated with the Default Calendar, use Select a date to specify a date or
select end of time.

Incentive Management Admin Design Guide

Getting Started PUBLIC 45
6. Choose Apply.

 Note

A new version of an object is created if you change the effective dates of an existing version of the object.
Ensure that items that refer to the object are still valid if you expand or reduce the effective range of an
object version. For example, a plan with an effective range from January 1999 to December 2005 can
be expanded to create a new version from January 2006 to end of time. Referring objects effective from
January 2001 to December 2004 are not valid for this new version.

Editing a Version of an Object

You should edit the current version of an object if you need to make a change to only that version. For example,
if you need to update a participant’s current salary, you would edit the current version of the participant object.
However, if you need to make changes to a version of an object other than the current version, you can simply
enter the information into respective fields and choose OK to save the changes.

The Versions for the Object dialog contains an effective date versions area at the top. All the tabs that are
accessible for the original object are also accessible from this dialog. By default, the version related to the
default period is displayed. The Versions for the Object dialog and the effective from date is highlighted.

The list of versions in the summary pane on the left allows selection of a particular version. The currently
selected version is highlighted in blue, while the non-selected versions are not shown in color. Details related to
the selected version reflect in the details pane on the right.

To select a different version, choose the version in the summary pane. The effective from and through dates
for the selected version areversion displayed in the drop-down boxes below the effective date timeline. The
following illustrates a single compared to multiple versions in the Versions for Object dialog.

 Note

You cannot change object attributes over multiple versions that are part of the object’s logical key (the
logical key is what defines the object as unique from other objects of the same type). For example, to
change a participant’s ID over multiple versions, you have to change the ID on each effective version
individually because the ID is part of the participant’s logical key. Change the information for the selected
version or versions. For example, if there was a spelling error in a participant’s name, you would edit the
version or versions that contain the erroneous information.

Incentive Management Admin Design Guide

46 PUBLIC Getting Started
End Dating an Object

If you have an object that is no longer active but cannot be deleted, you can change the effective end date of
the last version of that object to a specific date.

1. To end date an object, search for the object or objects to be end-dated in any workspace.
2. Select the object to be end-dated in the Summary View panel of the workspace.
3. Choose Manage Version from the Ellipsis Menu (…) to view the versions for the Object.
4. Navigate to it using the single and double scroll arrows if the last version of the object is not displayed, and
then select it by clicking the bar in the Effective Date Versions timeline.
5. Specify the end date using the Select a date option in the Effective through (Effective End date) field.
6. Choose Okto save your changes and close the Versions for the Object dialog.

In most cases, end dating and object is preferable to deleting it. End-dated versions are not processed by the
user interface or calculation in later periods. The following rules apply to end dating participants and positions:

• If a participant or position has non-zero results data, you cannot end date the participant or position.
• You can end date a position or participant version if there are no results data associated with that version.
• If the credit start, credit end, process start and process end fields on a position version that is end dated
extend beyond the effective end date of that version, the position continues to be processed and/or
receive credits and payments.
• If you end date a position or participant and that have associated zero-value results data, these results data
objects display with a position of <unavailable>..

For example, if you have a now obsolete position that was effective from January 1999 to EOT and that position
has resulted from January 1999 to August 2007, you cannot delete the position but you can end date it by
doing the following:

• In Manage Version (Versions for Object), end date the position by changing the effective end date of the
last position version to August 2007.
• In the New Version dialog, create a new version of this position from September 2007 to EOT and assign a
different or null position.

Deleting a Version of an Object

You can also delete a version of an object using the Versions for Manage Version window (Manage Version
window). If deleting a version would create a gap between versions, you are given the option to fill the gap using
the previous or next version.

1. To delete a version of an object, search for the object in any workspace.

2. Select the object in the Summary View.
3. Choose Manage Versionfrom the Ellipsis Menu (…) to view the versions of the Object in the Edit Versions
window.
4. Select a version from the Start Date and End Date timeline
5. Choose Delete to delete the version.

Incentive Management Admin Design Guide

Getting Started PUBLIC 47
The Delete Version dialog displays if deleting a version would create a gap between versions.In this dialog,
perform the following:

• Select either previous version or next version to indicate how the system should fill in the timeline gap. If
you select previous, the effective date of the version being deleted becomes effective through the date of
the previous version. If you select next, the effective from the date of the version being deleted becomes
effective from the date of the next version.
• Click OK to close the Delete Version dialog.

Bulk Edit of Versions

In the Manage Version screen, you can select multiple versions holding Ctrl button and edit the enabled
fields. Choose OK.

The edited fileds are updated in the Summary View, Details View and in the Manage Versions screens.

This feature is available in the following workspaces:

• Participant
• Position
• Title
• Category
• Generic Classifier
• Product
• Customer
• Postal Code
• Fixed Value
• Variable

Incentive Management Admin Design Guide

48 PUBLIC Getting Started
4 Search

The system provides you with different search options, such as Simple Search, Advanced Search, and Related
Search. These options give you quick access to compensation and result-data for research purposes.

The search options enable you to do the following:

• Using Simple Search, you can enter keywords to search for specific information.
• Using Advanced Search, you can construct search queries to find specific objects in a workspace.
• Using Related Search, you can research the associations between data.

Related Articles

• Common Search Features [page 50]

• Simple Search [page 49]
• Advanced Search [page 52]
• Advanced Mode [page 55]
• Saved Searches [page 57]
• Related Search [page 58]

4.1 Simple Search

You can access a quick word-based search from most of the workspaces in the application. Simple search
performs a name search or a simple text search using the entered keywords, depending on the workspace and
active view.

Click Clear to reset the search text field.

Related Information

Search [page 49]

Incentive Management Admin Design Guide

Search PUBLIC 49
4.2 Advanced Search Features

The Advanced Search filter icon is displayed in the page header. When clicked, the section expands to display
the search criteria and other related settings.

To collpase the view, re-click the filter icon. The Advanced Search panel provides the following options:

Actions Operation

Apply Applies the search terms entered and performs the search.

Reset Clears the search dialog.

Save Saves the search query with a name. See Saving Advanced
Search Query [page 57] for details.

No Filters Applied Indicates if any serach filters are already applied in the dis-
played page.

Cancel Closes the dialog.

Filter Settings

The search criteria area in Advanced Search can be used to build complex queries across database tables.

The following features and options are specific to the search criteria area:

• Current Default Period: In the results data workspaces (Credits, Measurements, Incentives, Commissions,
Deposits, and Payments workspaces), the period associated with the Default Period automatically
becomes part of the search criteria. For example, if your default period is January 2008, when you perform
a simple search in the Credits workspace, Period = January 2008 is included as part of your criteria. When
you perform an advanced search in the Credits workspace, Credit Period = January 2008 is included as
part of your criteria. If you are performing a related search from a workspace to the Credits workspace,
either Period = January 2008 or Credit. Period = January 2008 is defaulted depending on whether the
related search is in advance search format. You cannot remove this period criteria; however, you can
change it.

Incentive Management Admin Design Guide

50 PUBLIC Search
• Combine multiple criteria with All Search Criteria: If multiple criteria are specified, you use the AND or OR
options to join them. If AND is specified, All Search Criteria must be met. If OR is specified, at least one of
the search criteria must be met.
• Ignore Case in Text Fields - If your search criteria includes a text field, enabling this option returns results
regardless of capitalization.

For example, if you are searching in the Positions workspace for all positions names that begin with the letter
A, your search criteria would be either Name Like A% or Name = A*. If you enable this option and there are
three positions that meet this criterion (Account Manager, Account Executive, and account rep), capitalization
is ignored and all three names are displayed (with names beginning with lowercase letters at the bottom).
If you disable Ignore Case, only those results that begin with capital letters (Account Manager and Account
Executive) are displayed.

Filter Criteria

Besides Field Name and Order, the following options are available if configured:

• Filter by business units - If your organization has created and implemented business units, you can use
this option to display only those objects that are associated with one or more business units. To specify
just one business unit, select the business unit from the drop-down. You can only select a business unit to
which you have been assigned.
• Filter by processing unit - If the the Enable Processing Unitscalculation preference is enabled, the Filter by
Processing Units drop-down is displayed and a selection is required. You can use this option to limit your
search to results associated with one or more processing units or results not associated with a processing
unit (<Unassigned>).

The search for the Related Objects action panel is similar, however, it does not include the Save and Manage.

Related Information

Simple Search [page 49]

Incentive Management Admin Design Guide

Search PUBLIC 51
Using Advanced Search Filters [page 52]
Using Advanced Mode [page 55]

4.3 Using Advanced Search Filters

In Advanced Search, you can construct a search by selecting specific fields. The fields that are available for the
search are based on the workspace that the search is launched from. For example, if a search is launched from
the Relationships workspace, only those fields applicable to searching Relationships are displayed. Advanced
Search is available in all workspaces except the Calendars and Customization workspaces.

In the Advanced Search and Search for Related Object dialogs, you can also specify additional sort and filter
options.

 Note

In general, only fields specific to the core database table are accessible using Advanced Search. If two or
more tables must be logically joined to perform a search, you must use Advanced Search. For example, you
can search directly for transaction information, but a search for payees or positions related to a transaction
requires a join and Advanced Search must be used.

Comparison Operators

The comparison operators that are available for building your search are dependent on the field specified. For
example, the operators available for a text field differ from those for a numeric or date field. The operators for
the various data types are listed in the following table.

Operators String (var char) Number Date Boolean

< (less than) yes yes yes n/a

> (greater than) yes yes yes

= (equal to) yes yes yes yes

<> (not equal to) yes yes yes yes

<= (less than or equal) yes yes yes n/a

>= (greater than or yes yes yes n/a

equal)

Contains yes n/a n/a n/a

Not Contains yes n/a n/a n/a

Incentive Management Admin Design Guide

52 PUBLIC Search
Operators String (var char) Number Date Boolean

Between n/a n/a yes n/a

Empty yes yes n/a n/a

In addition to the listed operators, the in operator in Advanced Search allows you to search for results data
(credits, measurements, incentives, commissions, deposits, and payments) that are not specific to a leaf-level
period. For example, if your calendar includes decades, years, quarters, and months, it is possible to find all
credits for a specific quarter or year. You do not need to search at the leaf-level, in this case, month.

Guidelines for Using Comparison Operators

Use these guidelines when constructing Advanced Search to search for dates and nullable fields:

• When you use the equal to the = operator to search for a date, the values on each side of the operator
must be exactly the same. In some cases, you cannot ensure that the values are the same. For example,
some numbers could be rounded off internally by the system so that there is no match. In these cases, use
greater than > or less than < instead of equal to (. For example, instead of using the criteria Start Date =
1/1/2008, use Start Date >= 1/1/2008 AND Start Date < 1/2/2008.
• The Is Empty and Is not empty is available for nullable fields only. It is not available for fields that are
required in a workspace. For example, if you are doing a search by title name, a required field, Empty is not
available.

Wildcard Operators

The system only supports wildcards in the trailing position, so you need to build search strings ending with
a wildcard (string* or string*string*)rather than beginning with a wildcard (*string or *string*string). Use the
asterisk* wildcard with comparison and equals operators, and the percent sign % wildcard with the Contains
and Not Contains operators. In general, % and * wildcards can be used in string searches using the following
guidelines:

• When using the Contains and Not Contains operators, you can use t % operator using the format
string%string%. For example, a last name search on the value M%t% returns results for all last names that
contain both M and t, such as Mitchell.
• When using the equal (=) and not equal (<> ) operators, you can use the * (asterisk) in the format
string*string*. For example, a last name search on the value M*t* also returns results for all last names
that contain both M and t, such as Mitchell.

 Caution

Your database can impact the ability to search for strings that contain special characters because your
queries must be translated into SQL. Consult your database documentation to determine what restrictions
apply. Do not use either of the wildcard operators without qualifying string text. For example, you should

Incentive Management Admin Design Guide

Search PUBLIC 53
 not use just an asterisk (*) or a percent sign in your searches. Using wildcards without qualifying string text
results in poor search performance.

 Note

In Advanced Search, you do not need to enclose strings in quotes, but in Advanced Search > Advanced
mode, it is required.

Advanced Search Example

For example, to specify the criteria to find all participants with a salary greater than $500,000, you would:

• Select “Base Salary” in the Field Name drop-down

• Select “greater than” in the Comparison drop-down
• Enter “500,000” in the Value field
• Click the Unit Type field icon in the “Value” field and select “USD” to indicate dollars

Performing Advanced Search

You can include one or more of the available fields for a workspace in your Advanced search. If generic
attributes are available and enabled for the workspace, you can also use them in your search criteria.

1. To search for information using advanced search, click the Advanced Search filter. If you are performing
a search in a results data workspace (Credits, Measurements, Incentives, Commissions, Deposits, or
Payments workspaces), the period associated with the default period automatically becomes part of the
search criteria.
2. (Optional). Select a saved search or define a new one.
3. Specify one or more criteria by doing the following:
• Select a field name. The fields available are dependent on the workspace.
• Select a comparison operator. The comparison operators available are dependent on the field
selected.
• Specify a Value for the comparison. If a numeric field value is selected, in most cases you must click
the Unit Type field icon to select a unit type. However, if the value has a predefined unit type—such
as the transaction Discount (%), transaction num units (quantity), and transaction value (currency)
fields—or is an integer, the unit type field icon is not displayed.
4. (Optional). Select a saved search or define a new one.
5. Click Apply.

 Note

Most unit types, such as USD (US dollars) produce an exact match. If you search for Unit Value > $100,
only dollar values greater than $100 are retrieved. However, when you specify the integer unit type, values
of all unit types are retrieved. For example, if you search for Unit Value > 100 (unit type = integer), all values
greater than 100, such as$100 (dollars) and £100 (British pounds), are retrieved.

Incentive Management Admin Design Guide

54 PUBLIC Search
Retrieving All Information Using Search

If the workspace does not have a default search option then the Summary and Detail view are blank when
you first enter the workspace on a particular tab. The system populates the workspace with the results of the
search. The search is restricted to the default calendar.

1. To retrieve information from the workspace, click Advanced Search.

2. Click Apply without entering any search criteria.

 Note

If you get the message No Records Found when searching in the Payments workspace, follow the message
instructions to enable the Generate Payment Summary options (payment summary settings).

4.4 Using Advanced Mode

Use Advanced Mode to perform a search that requires that two or more tables must be logically joined.

Advanced Mode uses SQL-like syntax to form a search. The field names available for the search are based
on the workspace. For example, if a search is launched from the Transactions workspace, only those fields
applicable to searching transactions are displayed. Some of the elements in Advanced Mode, as shown in the
image below, show features found in the Formulas workspace.

As you build your search expressions, selected literals are displayed in blue text and selected data fields are
displayed in black text in the edit pane. Information is validated as you enter the details.

Advanced Mode Syntax

In the edit pane, use the following syntax to enter search criteria:

• To represent field names (such as Participant.Last), double-click the literals and field names displayed in
the table, or type an asterisk (*) and select from a list of possible field names.
• To enter comparison operators, type an asterisk and select from a list of operators.

Incentive Management Admin Design Guide

Search PUBLIC 55
• To enter currency amounts, type the number with no format (for example, 10000) and then select from the
list of currency types that displays (for example, USD). The system formats the amount for you.

To enter strings, either:

• Enclose the string in double quotes; for example, “Burke”

• Use the asterisk as a wildcard character; for example, “B*”
• To search for a null value, enter null without double quotes, for example, Participant.Positions.Name =
nullAdvanced Search Examples

Use Advanced Search to search across objects or perform complex logic. For example, the following search
finds all Participants that report to VPs: Participant.Positions.Manager.Title.Name = “VP” You can get the same
results by navigating the workspaces as follows:

• Go to the Titles workspace

• Search for all titles whose name = “VP”
• Find related positions
• Find related subordinates
• Find related participants

This second example finds all Manager credits greater than $1000, plus all VP credits:

(Credit.Value > $1000 and Credit.Position.title = “Manager”) or Credit.Position.Title = “VP”

Performing Advanced Search with Advanced Mode

Select Advanced Search in the summary view panel. Advanced search is available from the list view in most
workspaces and in either the table or tree view in Transactions, Credits, and Deposits workspaces.

1. Click the Advanced Search filter in the workspace.

2. (Optional). Select a saved search or define a new one.
3. Select Advanced Mode. Specify one or more criteria by selecting the operators, literals, and values as
needed. If the data field selected is a numeric field, you must click the Unit Type field icon to select a unit
type.
4. (Optional) Specify sort and filter options.
5. Choose Apply .

 Note

Most unit types, such as USD (US dollars) produce an exact match. If you search for Unit Value > $100,
only dollar values greater than $100 are retrieved. However, when you specify the integer unit type, values
of all unit types are retrieved. For example, if you search for Unit Value > 100 (unit type = integer), all values
greater than 100, such as$100 (dollars) and £100 (British pounds), are retrieved. The fields available are
dependent on the workspace. For example, if the search is launched from a specific workspace (as shown
previously), fields applicable to searching for the specific workspace are visible. If Generic Attributes are
enabled, you can use them in your search criteria.

Incentive Management Admin Design Guide

56 PUBLIC Search
4.5 Saving Advanced Search Query

When you perform a search, you can save your query so you can quickly re-run it later. You can either save a
search with the search criteria fully entered, or save the search to be used as a template by saving the criteria
without entering the actual values.

Saving a Search Query

1. Perform the Advanced Search in the required workspace.

2. Choose Save
3. In the Save Filter dialog, enter the following:
• Enter a name for the search in the Name field of the Save Query dialog.
• In the Description field, you can optionally enter a description for the search, such as Hires after
12/31/2007” or “Products that Cost More Than 50K”.

• Select one of the following in the Type drop-down:

• Public—All users who have access to the workspace can use the search.
• Personal—Only the user who created the search has access to it.
4. (Optional) Check Make Default to have the system execute this search every time you access the
associated workspace.
5. Choose Save. The system saves the search with the specified name and the search displays in the Search
Name pane. You can later choose this search from the Current Search drop-down in the Advanced Search
dialog.

Using a Saved Search

1. To use a saved search in the Advanced Search screen, select the required search from the Saved Filters
list.
2. Select Apply to execute the search.

Incentive Management Admin Design Guide

Search PUBLIC 57
Deleting a Saved Query

You can delete your personal searches and public searches from the Advanced Search page.

1. Search and select the saved search to be deleted in Advanced Search.

2. Choose Delete Query. This results in a confirm message “Are you sure you want to delete the query below?”
3. Choose Delete.

4.6 Related Search Overview

In some workspaces, the Related Search view enables you to find information related to the objects selected
in the summary pane. For example, you can quickly retrieve the related positions assigned to a plan, including
those assigned by title.

Performing a Related Search

When searching for related information, the system finds the items that are effective in the default period. For
example, you can perform a simple or advanced search for a title in the Titles workspace.

If you perform a related search for positions for that title, only those positions that are currently associated
with that title are found.

The general rule with related searches is that only objects directly related to a selected object are found.
Objects that are indirectly related are not found. For example, if you select a rule in the Rules Wizard workspace
and perform a related search for fixed values, the search returns the fixed values directly referenced by the rule,
but not those referenced by a formula used in the rule. However, several exceptions to this rule do exist. For
complete information on what each related search for each workspace returns, refer to the specific section.

1. To find related information, search for an object or objects from any workspace.
2. Select an object or objects in the Summary panel.
3. Go to Related Search, select any object from the listed options or choose Advanced Related Search next to
the object link.
• Selecting the link displays search results for that object for the default period.
• In most workspaces and for most objects, selecting the Advanced Related Search icon displays the
Search For Related Objects dialog in advanced search format and the name of the selected object is
substituted for the object name.
However, when doing related searches from some workspaces and for some objects, the system does not
display the Search For Related Object dialog. Instead, the objects are retrieved immediately and the results
are displayed in the related workspace. If no results are found, the message No Records Found is displayed.
4. Specify one or more criteria in the search criteria area.
5. Choose OK.

If results are found, the system opens the workspace for the selected object, and the objects related to the
selected object are displayed. If no results are found, the message No Records Found is displayed.

Incentive Management Admin Design Guide

58 PUBLIC Search
5 Organization Data Overview

Organization data includes participants, titles, positions, position groups, and relationships. Organization data
facilitates the following:

• Identifies the personnel, called participants or payees, who are paid.

• Associates participants with a position, and more indirectly, a title.
• Associates position assignments with specific compensation plans.
• Identifies effective dates of employment, position assignment, and termination.
• Specifies roll relationships & emdash; relationships that define who can receive indirect (rolled) credits for
transactions from related positions.
• Specifies the reporting structure, a mirrored representation of your human resources (HR) organization
chart that shows how each of the positions in the company is related to a position hierarchy of your
organization structure.

As your company’s organization changes over time, you must change your organization data to accommodate
changes. For example, you might need to add or remove participants, create new positions, or change your
reporting structure when people transfer within departments, get promoted or leave the company.

The system provides a workspace in which you can create, edit, copy, and delete each kind of organization
data. You can also import data for participants, positions, titles, and relationships instead of manually entering
this data. You cannot import data for position groups.

Related Articles

• About Participants [page 59]

• About Titles [page 65]
• About Positions [page 67]
• About Position Assignments [page 78]

5.1 Participants Overview

Person or organization participating in your variable compensation program. Also called payee. A participant
can be either an internal employee or an external company, such as a dealer. As your organization changes, you
can modify your participant's information. At the same time, you can also import participants information.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 59
Participants Workspace

The Details View displays as an untabbed workspace if neither custom attributes nor reporting attributes
have been enabled for participants. However, if either or both have been enabled, a General Information tab is
displayed.

The following image shows the participants workspace with the General Information tab displayed.

The display name format for participants can be configured.

Creating a Participant

Use the participant's workspace to create participant information.

1. Choose Organization > Participants.

2. Choose Create. The New Effective Start and End Date dialog displays.
3. Specify the effective dates for the new participant, and then click OK. An empty row displays in the Position
Summary and empty Standard andCustom fields in the General Information section of the Position Details
panel.
4. Enter the participant's ID. The participant's ID should be a unique sequence of numbers and or characters
that identify the participant. This number (for example, an employee number) is often used to identify the
participant in other external customer systems.
5. If your organization has created and implemented business units, you can assign this participant to one or
more business units by selecting from the Business Units drop-down. You can only select business units to
which you as a user have been assigned.
6. Finish creating the participant by entering the information indicated in the following table.

Incentive Management Admin Design Guide

60 PUBLIC Organization Data Overview
Field Description

Name: Prefix A prefix such as "Mr." or "Ms."

Name: First The participant’s first name.

Note: If you don’t check Ignore Case, participant names sort

differently if they are not capitalized.

Name: Middle The participant’s middle name or initial.

Name: Last The participant’s last name; if you’re specifying a company

as a participant, put the company name here.

Note: If you do not check Ignore Case, participant names

sort differently if they aren’t capitalized.

Name: Suffix A suffix such as "Jr" or "PhD."

User Name The user ID the participant uses to log in to Incentive Man-
agement Admin.

E-mail The participant’s email address. The email address is now

extended to 100 characters.

Preferred Language Set the preferred language for the participant. System docu-
ments, distributions and notifications will be sent in the se-
lected language.

Tax ID An identifying number, usually provided by human resour-

ces. For example, some companies enter the participant’s
social security number.

Base Salary Usually the base, non-variable portion of the participant’s

salary. If you have more than one base unit type for currency,
the Unit Type field icon is displayed so you can select a
currency.

On-target earnings (OTE) is calculated using this base salary

and the target compensation provided in the Positions work-
space.

The base salary, if specified, displays in the Participant Plan

summary.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 61
Field Description

Hired (Optional) The date the participant first began working at

your company. You can enter a date or select a date using
the Calendar icon.

The hire date is the first date when a participant is eligible for
assignment to a position. It is not the date that compensa-
tion processing begins for this employee. Processing dates
are assigned to position assignments.

This date is not used in the calculation of compensation.

Terminated (Optional) The last date the participant worked at your

company. You can enter a date or select a date using the
Calendar icon.

This date is not used in the calculation of compensation.

Event Calendar Select the event calendar for participants. If no calendar

is selected, the participant inherits the Default event calen-

dar which is set in > Preferences System Preferences

Communicator Configuration Choose Default Event

Calendar .

 Note

If the administrator has enabled custom attributes for participants, then a custom fields section is also
displayed within the participant’s details view panel and to configure these fields you have to click or launch
Configure Detail View window.

Modifying a Participant

You can modify most of the information for a participant including the participant’s business unit. In addition
to the update permission for participants, you must also have the update permission for participant name
and participant terminate to modify the participant’s name or he terminated date. Similarly, to modify the
participant’s base salary and Tax ID number, you must have update permissions for Private Data in addition to
update permission for Participants. See the

 Note

If the version of the participant that must be modified is not currently displayed, select the current version
and choose Manage Version on the toolbar to open the Versions for Object.

1. Choose Organization > Participants.

2. Search for the participant or participants that you want to modify from the Participant summary.
3. Choose Edit on the Details View to modify the record.

Incentive Management Admin Design Guide

62 PUBLIC Organization Data Overview
4. If the administrator has enabled custom attributes for participants, then a custom fields section is also
displayed within the Participant's details view panel and to configure these fields you, use the Configure
Detail View option.
5. Choose Save.

 Note

If you are searching for a participant occupying a particular position, use Advanced mode in Advanced
Search and type the Participant.Positions.Name data field. For example, to find all Participants
who occupy positions that have names beginning with the word Sales, you would specify the
query Participant.Positions.Name = “Sales*??.You can also use Advanced Mode in Advanced search
to find only those Participants who have not yet been assigned to positions using the query
Participant.Positions.Name = null.

Terminating a Participant

When a participant leaves your organization, you can terminate that participant. Terminating a participant
involves setting the terminated date on a version of the object, normally the latest version. Adding a terminated
date to one version adds it to all versions. Terminating a participant does not affect calculation processing for
that participant. Compensation for the participant continues to be processed. This is useful, for example, when
the participant should continue to receive credit and compensation for sales made before the termination
date and receive compensation for items such as yearly bonuses. However, if compensation for the participant
should no longer be processed or only processed up to a certain date, you must change the Credit start, Credit
end, Process start, Process end dates of the participant’s position assignment accordingly. If the participant is
no longer considered active but should remain in the system, the participant can be end dated. This involves
setting the end date on the last version of the object to a specific date.

To terminate one or more Participants perform the following steps:

1. Choose Organization > Participants.

2. Search and select the Participant or Participants that you want to terminate from the Participants
Summary panel.
3. Choose Edit .
4. Set the Termination Date.
5. Choose Save.

 Note

The Terminated field is provided in accordance with your human resources system, which determines
how the last date of a participant is recorded at your company.

Finding Objects Related to Participants

You can find data related to one or more Participants by selecting the appropriate object option from the
Related Search pane. The available options and the data returned are as follows:

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 63
• Positions—returns the positions referring to the selected participant.
• Credits—returns the credits allocated to the selected participant.
• Measurements—returns measurements referring to the selected participant.
• Commissions—returns the commissions referring to the selected participant.
• Incentives—returns incentives referring to the selected participant.
• Deposits—returns deposits referring to the selected participant.
• Payments—returns the payments referring to the selected participant.
• Titles- returns the titles referring to the selected participant
• Distributions Tracking --returns the distribution track referring to the selected participant

To find objects related to participants:

1. Go to Organization > Participants .

2. Search for the participant or participants to whom you want to find the related objects.
3. Select the participant or participants from the Participants Summary panel.
4. Choose any related object from the Related Search, for example, Deposits. The Search for related objects
displays with the name of the selected object substituted for the object name.

Deleting a Participant

You can delete a participant that does not have any associated results data. For example, you can delete a
participant that was just created either manually or using import, even if the participant has been assigned
to one or more positions. You cannot delete a participant that has associated results data. You also cannot
delete a participant if that participant is assigned to a position and there are other objects (such as any credits,
measurements, and so forth) that are associated with the position assignment. In both these cases, you should
consider end dating it instead.

Deleting a participant removes the participant object from the repository. However, the audit log in the Audit
Log workspace retains information on the actions performed on the participant object, including its remove
(delete) date, and information about the object itself. If the participant is pre-assigned to a transaction,
it is recommended that you remove the pre-assignment before the participant is deleted. If the payee pre-
assignment is not removed, a warning occurs when running the calculation, but the calculation continues to
process.

 Note

To delete a particular version of a participant, use the Manage Version icon on the toolbar.

About Using Special Characters

Because the following special characters can cause potential access problems while viewing reports, SAP
discourages their use in position names and payee names in Incentive Management as well as in the User IDs
created on the user store and in the passwords. Also, restricting the use of these special characters ensures
compliance with SAP Authentication.

Incentive Management Admin Design Guide

64 PUBLIC Organization Data Overview
? (question mark) < (less than) & (ampersand)

; (semicolon) > (greater than) / (forward slash)

* (asterisk) ”r; (double quote) \ (back slash)

’r; (apostrophe) % (percent) : (colon)

5.2 Titles Overview

Title is used to group similar positions across the organization. Titles usually group positions related to job
functions. For example, 'Sales Representative' is a Title and 'Sales Representative for Northern District' is a
position. All sales representatives in the organization might share the same title, but each sales representative
holds a unique position. Because positions that are related by title are compensated in the same way within an
organization, companies often assign compensation plans by title. At the same time, you can also import titles.

Titles Workspace

The detail pane of the Titles workspace contains core tabs: the General Information tab, and the Assignments
tab. If the administrator has enabled custom attributes for titles, then a custom fields section is also displayed
within the Titles details view panel and to configure these fields you have to select theConfigure Detail View
window. You can create titles in the Titles workspace.

Creating a Title

1. Choose Organization > Titles .

2. Choose Create.
3. Specify the effective start and end date of the new title.
4. Choose Ok
5. Enter the title's name in the General Information section of the Title Details panel. As a best practice,
title names should not be the same as position names. Position and title names should be unique. If
your organization has created and implemented business units, you can assign this Title to one or more
business units by selecting from the Business Units drop-down. You can only select business units to which
you as a user have been assigned. See the Administrator Help for more information about business units.
6. Optional: Type description for the title.
7. Optional: Choose the Plan field, search a plan and assign a plan to the title. If custom attributes for titles
are enabled, then a Custom Fields section is also displayed within the Titles details view panel. To configure
the custom fields, choose the Configure Detail View option.
8. Choose Save.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 65
Modifying a Title

You can modify the name and description of a title, its plan assignment, and its custom attributes. If custom
attributes have been enabled. You cannot change the business unit of a title if doing so would break the
business unit integrity between the title and it is referring to (plans) and referred by (positions) objects.

1. To modify a title, choose Organization > Titles .

2. Select title you want to modify.
3. Choose Edit .
4. Change the following in the Title Details panel as required:
• In General Information, you can change the Title name, description, and business Unit.
• In Assignments, from the Plan tab, you can assign a new default compensation plan to all positions
sharing this title. You can override this default. Plan assignment by title is the recommended method
for assigning plans.
• If custom attributes for titles are enabled, then a Custom Fields section is also displayed within the
Titles details view panel. To configure the custom fields, choose the Configure Detail View option.

 Note

If the version of the Title that must be modified is not currently displayed, select the current version and
edit the standard fields.

Finding Objects Related to Titles

You can find data related to one or more Titles by selecting the appropriate object option from the Related
pane.

1. Choose Organization > Titles .

2. Search title or titles for which you want to find related data.
3. Choose any related object from the Related Search, for example, positions.

• If you are searching for related rule elements (fixed values, rate tables, territories, or variable), the objects
are retrieved immediately and the results are displayed in the related workspace. If no results are found,
the message No Records Found is displayed. Choose OK to close the message dialog
• If you are searching for related plans or positions, the Search For Related Object dialog displays with
the name of the selected object substituted for the object name. The Search For Related Objects dialog
displays with the name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Positions—returns the positions referring to the selected title.

• Plans—returns the plans that the selected title refers to.
• Fixed Values—returns the following:

• Fixed values directly used in the rules belonging to the title plan.
• Fixed values referred to by other rule elements, such as formulas, that are used in rules belonging to the
title plan.
• Fixed values used in the fixed value variable assignments where the variable assignment is by title. If the
variable assignment is by plan, the fixed value assigned to the title plan is returned.

Incentive Management Admin Design Guide

66 PUBLIC Organization Data Overview
• Rate Tables—returns the following:
• Rate tables directly used in the rules belonging to the title plan.
• Rate tables referred to by any other rule element, such as formulas, that are used in rules belonging to
the title plan.
• Rate tables used in rate table variable assignments where the assignments are by title. If the variable
assignment is by plan, the rate table assigned to the Title plan is returned.

• Territories—returns the following:

• Territories directly used in the rules belonging to the title plan.
• Territories used in territory variable assignments where the assignments are by title. If the variable
assignment is by plan, the territory assigned to the Title plan is returned.

• Variables—returns the variables used in the variable assignment of the selected Title.

Deleting a Title

You can only delete Titles that are not associated with any positions. Deleting a title removes the title object
from the repository. However, the audit log in the Audit Log workspace retains information on the actions
performed on the title object, including its remove (delete) date, and information about the object itself. If the
title is pre-assigned to a transaction, it is recommended that you remove the pre-assignment.

 Note

To delete a particular version of a Title, use the Manage Version option in the Ellipsis Menu (…) .

5.3 Positions Overview

Positions define specific, unique jobs that participants perform in each specific area of the company. There is
a unique position for each participant. Each position in the system is grouped under a job title. The positions
created in the sytsem typically mirror the positions on your organization chart and reflects subordinate and
management positions. As your company grows, you can create new positions and modify existing positions as
job responsibilities in your company evolve.

Positions Workspace

The Summary View in the Positions workspace can be viewed in both list and tree view. The Detail View ,
displays the General Information , Assignments, Relationships and Associations tab. If the administrator has
enabled additional attributes such as custom fields, reporting attributes, and extended attributes, respective
details are displayed.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 67
Positions Workspace in List View

The following image shows the summary pane of the Positions workspace in list view. In the list view individual
positions are displayed.

The display name format for positions can be configured. .

Positions Workspace in Tree View

The following image shows thePositions workspace in the tree view. In the tree view, the reporting structure
your organization has created is displayed. The tree view displays the number of positions attached to a node.

General Information Tab

You can edit the standard fields as needed.

The Finalized Period option in the General Information tab lists all the finalized periods for the position

In the the Plan field, you can assign a default compensation plan directly to a position or indirectly to all
positions sharing a title. .

 Note

If a plan is assigned by title, the Plan field is replaced by the name of the title plan and is followed by the
word “(Title)"

Incentive Management Admin Design Guide

68 PUBLIC Organization Data Overview
Relationships Tab

You can use the Relationships tab to view roll relationships for a selected position.

Associations Tab

The Associations tab shows all the subordinates directly reporting to the selected position.

Assignments Tab

If the plan assigned to the title includes rules that include one or more variables, those variables are displayed
in the variables assignment area. Also, if a plan has been assigned to the title and a plan summary view has
been defined for the plan, you can use set the viewing locale and period then use the View Plan Summary
option to view information about the plan.

Creating a Position

Positions are typically created for employees, but can also be assigned to partners, distributors, or other
people associated with your organization.The system allows you to process compensation for unoccupied
positions (no assigned participants yet), or to process positions assigned to participants at different times
in the same pay period. The system allows you to allocate credit for sales to the position continuously for
reporting, analysis, rollup, and team bonus calculation purposes. You can move positions or create additional
positions to accommodate organizational changes.

1. To create a position, choose Organization > Positions .

2. Choose Create. The New Position dialog displays.
3. Specify the effective dates for the new position, and then choose OK.
4. Enter a name for the position. As a best practice, position names should not be the same as title names.
Title and position names should be unique.If your organization has created and implemented business
units, you can assign this position to a business unit by selecting from the Business Units drop-down.
Positions, like position groups, can be assigned to only one business unit. You can only select a business
unit to which you as a user have been assigned.

 Note

If processing units have been enabled (using the Use Processing Unit calculation preference), you
should assign a business unit when you create the position.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 69
5. (Optional) Enter a Description for the position.
6. Specify a Title for this position. The effective dates of the title must be the same or longer than those of the
position. You cannot select a title that does not meet this criterion.
7. (Optional) Specify a Manager for this position. This is the position to which this position reports. The
effective dates of this manager must be the same or longer than those of the position. You cannot select a
manager that does not meet this criterion.

 Note

If processing units have been enabled (using the Use Processing Unit calculation preference), you
should assign a business unit when you create the position.

8. (Optional) Specify a payee. This is the participant currently occupying this position. The effective dates of
this participant must be the same or longer than those of the position. You cannot select a participant that
does not meet this criterion.
9. (Optional) Specify a position group.
If the Enable Processing Units in System preference is enabled, all positions in a position group must have
the same processing unit and business unit mapping.
10. (Optional) Enter a Target Compensation. This is the position’s target variable compensation.
The target compensation is the goal amount of a participant’s salary that comes from variable
compensation. On-target earnings (OTE) is calculated using this target compensation and base salary
provided in the Participants workspace. The target compensation, if entered, displays in the Participant
Plan Summary.
11. Consider the following:
1. To override the credit or processing effective dates for the position, modify or change processing dates
by changing Credit start, Credit end, Process start and Process end dates
2. (Optional) To complete your position:
• Choose the Plan drop-down, to assign a plan to the position.
• Choose the Relationship tab, to specify roll sources and receivers.
• Enter Custom attributes values, If the administrator has implemented custom attributes.
12. Choose Save.

Specifying Subordinate Positions

To specify subordinates for the position (that is, positions that report to this position), you create new positions
with this position as the manager.

1. Choose Organization > Positions .

2. Select Tree view to display the reporting structure.
3. Expand the hierarchy until the position for which you want to create subordinates is displayed.
4. Select the position.
5. Choose New in the Action panel.
6. Create the new position.
7. Repeat steps four through six to create additional subordinates.

Incentive Management Admin Design Guide

70 PUBLIC Organization Data Overview
Viewing Roll Relationships from Positions Workspace

You can also see roll relationships from the perspective of individual positions.

1. Choose Organization > Positions .

2. Search for the position for which you want to view the roll relationships.
3. Select the position in the Summary panel.
4. Choose the Relationship tab to view the roll relationships for that position.

The left pane displays the positions that roll credits to the selected position. The right pane displays the
positions that the selection position rolls credits to.

Deleting a Position

You can delete a position that was just created either manually or using import. You cannot delete a position
if that position has associated results data. In this case, you should consider end dating it instead. Deleting
a position removes the position object from the system. However, the audit log in the Audit Log workspace
retains information on the actions performed on the position object, including its remove (delete) date, and
information about the object itself.

 Note

To delete a particular version of a position, use the Manage versionon the toolbar. If the position is
pre-assigned to a transaction, it is recommended that you remove the pre-assignment.

Modifying a Position

You can modify some attributes of a position with few or no restrictions. For example, the name, description,
and Target compensation can all be easily modified.

1. Choose Organization > Positions .

2. Search for the position or positions to be modified. If you have assigned plans to positions using titles
as well as directly, you must use Advanced Search to find all positions that reference a specific plan.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 71
 For example, to find all positions that reference a plan called Sales Plan, regardless of whether the plan
is assigned by position or title, you should perform an Advanced Search using Advanced Mode with the
following search criteria: Position.Plan.Name=”Sales Plan" and Position.Title.Plan.Name=”Sales Plan".
3. Select the position or positions in the Summary panel.
4. Make your changes in the detail panel of the Positions workspace,
5. Choose Save.

 Note

As a best practice, position names should not be the same as title names. Title and position names should
be unique. You should keep this in mind when renaming a position.

The following restrictions apply to the other attributes of a position:

• The title, manager, and payee attributes of a position can be modified, but only objects that do not break
business unit integrity can be selected.
• The position group can be modified, but only position groups that belong to the same processing unit can
be selected.
• The business unit of the selected version of a position can be modified, if the following are true:
• There are no associated calculation results associated with the selected position version.
• The business unit selected must be associated with the same processing unit as the business units
assigned to the other versions of the position. In other words, different versions of a position can have
different business units as long as all the business units are associated with the same processing unit.
• Credit Start, Credit End, Process Start, Process End dates can be modified, if certain requirements are
met.
• You can modify some attributes of multiple positions at once; for example, you can change the Position
Group or the Manager for a group of positions. You cannot multi-select positions and update the business
units of those positions.

 Note

You can only assign one business unit to positions and position groups. There are no Multiple options in the
Select Business Unit drop-down.

 Note

If the version of the position that must be modified is not currently displayed, select the current version
and choose the Manage versions option to open the versions for Object dialog. If the version of the title that
must be modified is not currently displayed, select the current version and choose the Edit Versions icon.

Editing the Effective Date of a Position Version

You can edit the effective dates for a position version if you have calculation results associated with it;
however, the new effective dates must correspond to the calculation run dates. In other words, at least one
position version must have effective dates that cover the calculation run period. For example, if you have two
position versions effective from 01/01/00 to 05/31/06 and 06/01/06 to EOT respectively, and you also have
calculation results for January 2007, you cannot change the effective date range for the second version from
06/01/06 to 12/31/06.

Incentive Management Admin Design Guide

72 PUBLIC Organization Data Overview
Removing a Participant (Payee) from a Position

Removing a participant (payee) from a position is the same as ending the association between the participant
and the position. If the participant is to be removed from a version other than the one currently displayed,
choose Manage version on the toolbar and select the correct version.

1. Choose Organization > Positions .

2. Search for the position from which you want to remove the Participant.
3. Choose Edit in the Details panel and choose Close button in the participant filed. This ensures participant
field is successfully removed from the Position.
4. Choose Save.

Participants Transitioning in and out of a Position

The system provides custom credit and calculation processing dates to handle the following cases:

• A participant leaves a position and continues to be eligible to receive credits and payments from that
position until a specified date.
• A participant leaves a position, no longer receives credits, but continues to receive payments from that
position until a specified date.
• A participant takes a leave of absence and does not receive any credits during that time, but continues to
receive payments in the same position.
• A participant takes a leave of absence, does not continue to receive credits or payments, but continues in
the position, and resumes receiving credits and payments after the leave of absence is over.

In these cases, a participant can continue to hold a position in some form (for credit and calculation
processing) while another participant enters the position. The participant leaving the position can still be paid
for that position for some period of time after leaving, even though another participant has already started
receiving credit and payment for the position. A position receives credits and other calculation results (such
as payments) based on the position’s effective dates. However, you can additionally specify custom dates for
when the position should continue to receive credits and other calculation results data. The system does not
process positions that do not have assigned participants.

Guidelines for Using Position Credit Start, Credit End, Process Start, and
Process End

When working with Credit Start, Credit End, Process Start, and Process End dates, keep the following facts in
mind:

• The processing start date has been within or equal to the effective start date of the position.
• The processing start date has to be before (cannot be the same as) the processing end date.
• The effective end date of the position has to be the same or after the processing end date.
• The credit and processing end dates can extend after the position's effective end date only if the next
position version is associated with a different or no participant.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 73
• Credit processing dates must be within the range of position processing dates.
• Credit Start, Credit End, Process Start and Process End dates cannot begin before the effective date of the
position. Credit Start, Credit End, Process Start and Process End dates begin after the position’s effective
date, or even after the position’s effective end date.

The following table summarizes how the Credit Start, Credit End, Process Start and Process End dates for a
position (Receiving Credit and Is Processing) affect the position processing. Receiving Credit and Is Processing:
Interactions

Receiving Credit enabled Is Processing enabled Effect

X X The position assignment receives

credit, and payment is calculated for it.

X The position does not receive any new

credits, but existing credits are proc-
essed.

Note: If you are creating a manual credit

or importing a credit and the credit’s
compensation date is within the posi-
tion’s processing dates but outside the
position’s credit dates, The system is-
sues a warning and allows the credit to
be created.

The position assignment is disabled.

Use this combination to retain the posi-
tion assignment even though no partici-
pant is currently assigned to it.

To terminate a position assignment,

you must assign it an effective end
date. Examples are included in the fol-
lowing sections.

 Note

If you have modifiedCredit Start, Credit End, Process Start, and Process End dates, you can specify Is
Processing effective dates and not specify Receiving Credit effective dates. However, if you do not specify Is
Processing effective dates, you cannot specify Receiving Credit effective dates.

Direct credits are processed based on their transaction’s compensation date and rolled credits are processed
based on their source credit’s compensation date. Following are some examples that cover some special cases
of positions with Credit Start, Credit End, Process Start, and Process End dates.

Incentive Management Admin Design Guide

74 PUBLIC Organization Data Overview
Example: Participant Replaced in a Position

Melissa is leaving a position, and Mona is replacing her. Melissa should receive credits and payments for fifteen
days after she leaves the position, during which time both participants should receive credits and payments.
Melissa is assigned to Position A with the following effective dates:

• Position version #1 effective: 01/01/2006 to 02/29/2008

• Position is receiving credits effective 01/01/2006 to 03/15/2008
• Position is processing effective 01/01/2006 to 03/15/2008

Mona is assigned to Position A with the following effective dates:

• Position version #2 effective: 03/01/2008 to End Of Time

• Position is receiving credits effective 03/01/2008 to End Of Time
• Position is processing effective 03/01/2008 to End Of Time

In the March 2008 period, both Melissa and Mona receive credits based on transactions with compensation
dates between 3/1/08 and 3/15/08. For transactions that have compensation dates between 3/16/08 and
3/31/08, only Mona receives credits.

For Melissa’s position assignment, Credit Start, Credit End, Process Start, and Process End dates (custom
processing dates) are specified. For Mona’s position assignment, no Credit Start, Credit End, Process Start,
and Process End dates(custom processing dates) are specified; the credit and processing dates inherit the
effective dates from the position.

Example: Participant on Leave

Jeff is assigned to Position B starting on 01/01/2006 with no end date specified, this is version #1. He is taking
a leave of absence from 07/01/2008 to 08/31/2008, during which time he does not receive new credits but
does receive payments based on credits that have already been allocated to him. When you create a version #2
of the position for the leave of absence, the system automatically sets the effective to date on version #1 and
creates a third version of the position. The positions that now exist are as follows:

• Version #1, which is effective from 01/01/2006 to 6/30/2008

• Version #2, which is effective from 7/1/2008 to 8/31/2008 (with empty Credit Start,Credit End,Process
Start and Process End dates
• Version #3, which is effective from 9/1/2008 to End Of Time

The following bullets describe the effective dates for each position version after you have created the new
position version, version #2, to cover the leave of absence.

• The unversioned position was originally effective January 2006 to End of Time. After you create the new
version, Version #2, to cover the time for the leave of absence, the original version, Version #1, becomes
effective dated from January 2006 to June 2008.
• Version #2 of the position is effective during the leave of absence time, July 2008 to August 2008. For this
version of the position, no credits are received and no payments or other results data are processed.

• Version #3 of the position is effective after the leave of absence time, from September 2008 to End of
Time. The sytsem automatically creates this version of the position to accommodate the need for the
position version for the leave of absence.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 75
Example: Held, Rolled Credit

Position C is effective February 15, 2008, to End Of Time, and does not have Credit Start, Credit End, Process
Start, and Process End dates specified, the credit and processing effective dates match the position’s effective
dates. Position C receives rolled credits from Position D, a subordinate. Position D has a held, rollable credit
with a release date of March 1, 2008. (The release date is also the credit’s compensation date.) This credit is
associated with a transaction that has a compensation date of February 5, 2008. Position C receives this held,
rollable credit during calculation processing in March 2008.

Example: Participant Leaving a Position

Steve is leaving his position at the end of January, and there is currently no replacement. Steve continues to be
processed and receives payments until the end of the following month.

To discontinue the position assignment but retain the position, you create a new version and delete the
participant from the new position version. You then edit the earlier position version and specify Credit Start,
Credit End, Process Start and Process End dates that extend to the end of the following month.

The position has two effective versions:

• One position version is effective in January 2008 (January 1, 2008, to January 31, 2008). This position
version has Credit Start, Credit End, Process Start, and Process End dates modified, and the effective
dates are January 1, 2008, to February 28, 2008. Steve is assigned to this position version.
• The other position version is effective in February 2008 (February 1, 2008, to End Of Time). This version
does not have a participant assigned to it, and no Credit Start, Credit End, Process Start, and Process End
dates are specified.

During calculation processing in February, the sytsem processes the January version of the position, even
though February is not within the position assignment’s effective dates. The January position version is
processed in February because the Credit Start, Credit End, Process Start, and Process End dates are effective
during February. The February position version is not processed because it does not have an associated
participant.

Specifying Credit Start, Credit End, Process Start, and Process End dates for
Position

You can override the credit or processing effective dates for the position using Credit Start, Credit End, Process
Start and Process End dates Credit Start, Credit End, Process Start and Process End dates are most commonly
used when a participant leaves a position or takes a leave of absence.

1. Choose Organization > Positions .

2. Search for the position for which you want to specify Credit Start, Credit End, Process Start, and Process
End dates.
3. Select the position in the Summary panel.
4. Choose Manage version to open the Versions for Object dialog, then select the correct version If the
appropriate version of the position is not displayed,

Incentive Management Admin Design Guide

76 PUBLIC Organization Data Overview
5. Select Credit start, Credit End, Process Startand Process End dates to enable and display the Receiving
Credit and Is Processing options.
• The effective dates of the current position version have defaulted for both options. If these dates are
not changed, the Credit Start, Credit End, Process Start, and Process End dates check box is disabled
when the position version is saved.
6. Configure Credit start, Credit end, Process start, Process end dates.
• To have the position receive credits, payments, and other results data during calculation processing,
leave the Receiving Credit option enabled. Then specify the range of effective dates during which the
position should receive credit.
If you disable the Is Processing option, the system automatically disables the receiving credit option
because to receive credits, the position must be processed. For the same reason, if both options are
disabled, and you enable the Receiving Credit option, the Is Processing option is automatically enabled.
The Receiving Credit and Is Processing dates can be different, as long as the Is Processing dates include
the Receiving Credits.
• To override the effective dates during which the position is eligible for calculation processing and
have the position receive payments and other results data but not credits, enable only the Is
Processing(process start and process end) option and specify the range of effective dates.
• To have the position not receive either credits or any other results data, deselect both the Receiving
Credit and the Is Processing options.
• To make the position version credit and processing dates match the effective dates of the position
version itself, deselect Credit start, Credit end, Process start, Process end dates
7. Choose Save.

 Note

For both Receiving Credit and Is Processing dates, if you enter the first day of a period as the start date
of your effective dates range when you save your changes the date automatically defaults to the period
date. For example, if you enter 02/01/2008 as the start date when you save, the start date is displayed as
February 2008.

Finding Objects Related to Positions

You can find data related to one or more positions by selecting the appropriate object option from the Related
pane.

1. To find objects related to positions, choose Organization > Positions workspace.

2. Search for the position or positions for which you want to find related objects.
3. Select the position or positions in the Summary panel.
4. Choose the object in the Related panel, for example, titles.

If you are searching for related plans or related rule elements (fixed values, rate tables, territories, or variables)
the objects are retrieved immediately and the results are displayed in the related workspace. If no results
are found, the message No Records Found is displayed. If the object option selected was not plans or a rule
element, the Search For Related Objects dialog displays with the name of the selected object substituted for the
object name.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 77
The available options and the data returned are:

• Participants —returns the participants associated with the selected position.

• Titles —returns the title associated with the selected position.
• Managers —returns the manager for the selected position.
• Subordinates —returns the subordinates to the selected position, that is, the position that is referring to
the current position as manager.
• Position Groups —returns the Position Group associated with the selected position.
• Quotas —returns the quota assignments for the selected position.
• Credits —returns the credits referring to the selected position.
• Measurements —returns the measurements referring to the selected position.
• Commissions —returns the Commissions referring to the selected position.
• Incentives —returns the incentives referring to the selected position.
• Deposits —returns the deposits referring to the selected position.
• Payments —returns the payments referring to the selected position.
• Fixed Values—returns the following:
• Fixed values directly used in the rules belonging to the position plan.
• Fixed values referred to by other rule elements, such as formulas, that are used in rules belonging to
the position plan.
• Fixed values used in the fixed value variable assignments where the variable assignment is by position.
If the variable assignment is by plan, the fixed value assigned to the position plan is returned.
• Rate Tables—returns the following:
• Rate tables directly used in the rules belonging to the position plan.
• Rate tables referred to by any other rule element, such as formulas, that are used in rules belonging to
the title plan.
• Rate tables used in rate table variable assignments where the assignments are by title. If the variable
assignment is by the plan, the rate table assigned to the position plan is returned.
• Territories—returns the following:
• Territories directly used in the rules belonging to the position plan.
• Territories used in territory variable assignments where the assignments are by position. If the variable
assignment is by the plan, the territory assigned to the position plan is returned.
• Plans—returns the plan that is directly assigned to the selected position, or the plan that is assigned by
title.
• Variables—returns the variables used in the variable assignment of the selected position.

5.4 Position Assignments Overview

You create a position assignment by assigning a participant to a specific position for a specified duration of
time. The sytsem calculates variable compensation for the position assignment. During the compensation
process, credits, commissions and bonuses, and deposits are allocated to position assignments. Position
assignments (also called position relationships) can also be imported.

Incentive Management Admin Design Guide

78 PUBLIC Organization Data Overview
  Note

A position can only have one participant at a time, but a participant can be assigned to multiple positions.

Assigning a Participant to a Position

A participant is assigned to a version of a position within an effective date range that defaults to the current
date through end of time. You can change the effective date range using the Manage Version button, or create a
new effective date range using the New Version button. You can assign only one participant to a position at any
given time. To assign another participant to that same position, you must create a new version of the position
and assign the new participant to that version.

1. Choose Organization > Positions.

2. Search for the position you want to assign.
3. Select the position in the Summary panel.

 Note

If the required assignment is for an effective date range other than the one currently displayed, choose
the Manage version option to open the Versions for Object dialog, then select the correct version or
versions.

4. Specify the name of the participant to be assigned in the Payee field from the Details > General Information
tab.
5. Choose Ok.

Date Constraints for Position Assignments

There are a few date constraints for assigning participants to positions:

• Unless you use a transition position, effective date ranges cannot overlap for a given position assignment.
Only one participant can be assigned to a position at a time, but a participant can be assigned to multiple
positions at a time.
• Direct credits are created according to the associated transaction’s compensation date if the transaction’s
compensation date is within the effective date range for the position version and Credit start and Credit
end dates are specified. The credit’s compensation date is the transaction’s compensation date.

These dates become important when deciding or analyzing where credits are created and processed.

 Note

To process unoccupied positions, use TBH as an unspecified participant in that position.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 79
5.5 Relationships Overview

As you create positions in the positions workspace, the system automatically creates a roll type called
reporting. This roll type mirrors your organization’s reporting structure and credits are allocated accordingly.
For example, a sales manager can receive commissions based on a subordinate salesperson's sales transaction
credits. In turn, these credits from which commissions are calculated are typically rolled up to the manager's
manager.

As a best practice, you should create another roll type that mirrors your reporting relationships and then make
any additions or changes to the copy. Creating a separate roll relationship that parallels the reporting structure
allows you the flexibility to change roll relationships without compromising the reporting structure. For
example, create a roll type called rollup and create relationships between each position to mirror the reporting
structure. In the relationships workspace, you can create additional roll types and reporting relationships. This
can be required because organizations often compensate people outside the sales team and it is common
to have credits roll from one person to a peer (sometimes called rollover roll type). You can also import
relationships into the system.

Related Information

Using the Relationships Workspace [page 80]

5.5.1 Using the Relationships Workspace

You can access the Relationships workspace from the Organization menu. Depending on your need, you can
visualize, review, and manage Relationships using the Tree View or Table View.

Tree View: This view displays a list of the existing Roll Types. It is a hierarchical representation of all Roll Types
and Relationships. You can use this view to drill down to each level of a Roll Type. You can also create Roll Types
and Relationships in this view.

Table View: This view displays existing Relationships between the Source and Receiver participant. It provides a
list view of all Relationships. You can configure Relationships between Positions in this view.

Incentive Management Admin Design Guide

80 PUBLIC Organization Data Overview
You can perform the following actions using the respective options in the toolbar and in the Ellipsis Menu (…) .

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 81
Action Description

Create To create a Roll Type (Tree View only):

1. Choose Organization > Relationships.

2. Select Tree View. Roll Types can be created only in Tree view.

3. Choose Create and select New Roll Type.

4. Enter a name for the Roll Type and click Save.

To create a Relationship in Tree View:

1. Choose Organization > Relationships.

2. Select Tree View.

3. Choose Create and select New Relationship.

4. Set the Effective Start Date and the Effective End Date for the relationship.

5. The Roll Type is populated depending on your location in the hierarchy.

6. Select the appropriate Receiver position if it’s not already populated.

7. Select the appropriate Source position. You can add up to 10 Sources.

8. Choose Save. The Source-Receiver relationship in this Roll Type is created.

Incentive Management Admin Design Guide

82 PUBLIC Organization Data Overview
Action Description

To create a Relationship in Table View:

1. Choose Organization > Relationships.

2. Select Table View.

3. Choose Create.

4. Set the Effective Start Date and the Effective End Date for the relationship.

5. If you have selected a Roll Type, the Roll Type and Receiver fields are populated in the
pop-up window depending on your selection. If these fields are not populated, select a Roll
Type and proceed.

6. Select a Receiver position (if not populated).

7. Select the appropriate Source position. You can add up to 10 Sources.

8. Choose Save. The Source-Receiver relationship in this Roll Type is created.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 83
Action Description

Edit To edit a Roll Type (available only in Tree View):

1. Choose Organization > Relationships.

2. Select Tree View.

3. Select the Roll Type you want to edit and chose Edit in the Ellipsis Menu (…).

4. Update the name of the Roll Type and click Save to save your changes.

To edit a Relationship:

1. Choose Organization > Relationships.

2. Select the desired view (Tree View or Table View).

3. Select the record you want to edit and choose Edit in the Ellipsis Menu (…). In Tree View,
the edit option is enabled when you select a Source. You can edit the Source, Receiver, and
Effective Dates in the pop-up window.

4. Choose Save to save your changes.

Copy You can create a copy of an existing Roll Type or Relationship. When copying a Roll Type, the
Relationships from the original Roll Type are not copied.

To copy a Roll Type or Relationship:

1. Choose Organization > Relationships.

2. Select the desired view (Tree View or Table View).

3. Select the record that you want to copy and choose Copy in the Ellipsis Menu (…). In Tree
View, the copy option is enabled when you select a Roll Type or Source.

4. Update the desired fields and click Save.

Delete You can delete a Roll Type from the Relationships workspace only when the Roll Type no
longer has any relationships or if it's not referenced in rules or distributions. If you try to delete
the Roll Type with existing relationships, an appropriate message is displayed.

To delete a Roll Type or Relationship:

1. Choose Organization > Relationships.

2. Select the desired view (Tree View or Table View).

3. Select the Roll Type or Relationship that you want to delete and choose Delete in the Ellipsis
Menu (…) . In Tree View, the delete option is enabled when you select a Roll Type or Source.

Incentive Management Admin Design Guide

84 PUBLIC Organization Data Overview
Action Description

Manage Versions You can create new versions and edit existing versions using the Manage Version option.

To create or manage versions:

1. Choose Organization > Relationships.

2. Select the desired view (Tree View or Table View).

3. Select the required Roll Type or Relationship and choose Manage Version in the Ellipsis
Menu (…). In Tree View, the manage version option is enabled when you select a Source.

4. In the Edit Versions window, edit the effective dates as needed and click OK.

See Object Versions Overview [page 45] for details.

Audit Audit history displays a quick summary of the Roll Type and Relationship updates. All the
changes performed on the selected Roll Type and Relationship are displayed.

To audit a Roll Type or Relationship:

1. Choose Organization > Relationships.

2. Select the desired view (Tree View or Table View).

3. Select the Roll Type or Relationship that you want to audit and chooseAudit to view the
Audit Summary. In Tree view, the audit option is enabled when you select a Roll Type or
Source.

See Viewing Audit History of an Object [page 44] for details.

CSV Export You can export the Relationships to a CSV file.

In Tree View, you can export a single relationship (the currently selected record) or a full Roll
Type (all displayed records).

In Table View, you can export records in bulk. You can select multiple records using the SHIFT
key.

To export a record:

1. Choose Organization > Relationships.

2. Select the appropriate view (Tree View or Table View).

3. Select the records you want to export and choose Export Data in the Ellipsis Menu (…) and
proceed.

See Data Loaders [page 29] for details.

Search Simple Search enables you to perform a quick word-based search across the records.

In Tree View, you can conduct a Simple Search within the currently expanded node. For exam-
ple, if you expand the Roll Type to the first level and this first level has 2000 Relationships, you
can search for a specific relationship that exists within the expanded level. If you are unsure
what level the relationship you are searching for exists in, it’s recommended to use Table View.

In Table View, you can search for a Receiver or Source and all associated records are returned.

Incentive Management Admin Design Guide

Organization Data Overview PUBLIC 85
Action Description

Advanced Search The Advanced Search option is available only in Table View. See Using Advanced Search Filters
[page 52] for details.

Related Search The Related Search option is available only in Table View. Related Search allows you to nav-
igate from the Relationships workspace to the Positions workspace to view details of the
associated Receivers or Sources (for a single record). See Related Search Overview [page 58]
for details.

Related Information

Relationships Overview [page 80]

Incentive Management Admin Design Guide

86 PUBLIC Organization Data Overview
6 About Plans

A compensation plan is also referred as a Plan. A plan includes a set of rules that specify how compensation is
processed for each position that is assigned to the plan.

Plans model the compensation policies for a group of participants who occupy positions that have similar
compensation requirements in your organization. You can create and edit plans in the system. You can also
import plans via XML.

 Note

Plan names should be unique. Plans with the same name cannot be imported.

Additionally, The Plan Components feature allows you to set up Compensation Plans using Factory Data
Templates. There are 20 predefined templates, which cover the most common compensation scenarios.

Related Articles

• Plans Wizard Workspace [page 87]

• Creating a Plan [page 89]
• Adding Rules to a Plan [page 90]
• Plan Assignments [page 91]
• Editing a Plan [page 92]
• Finding Objects Related to Plans [page 93]
• Plan Components [page 94]

6.1 Plans Wizard Workspace

In the Plans Wizard workspace, you can create or edit plans, copy plans, add or remove rules from plans. You
can also create rules dynamically in the Plans Wizard workspace.

Navigate to Plan Data > Plans Wizard to access the Plans Wizard workspace.

General Information

The following image shows the General Information tab.

Incentive Management Admin Design Guide

About Plans PUBLIC 87
Assignments Tab

In the Assignable area, you can see what positions and titles have been assigned to the plan. In the Variable
Assignments area, you can view and assign rule elements to the variables that have been associated with the
plan.

Multi-Select/Add Rules to the Plan Component Section

Use the Ctrl key to select multiple plan components and add them in bulk to a plan.

To multiselect rules to add them to plan components:

1. Go to the Plans Wizard workspace and select a plan to edit it in the plan details.
2. Select the Plan Components option from the View by drop-down. Choose the Add Plan button and you can
view a list of plan components.
3. Use Ctrl key and select multiple plan components and click the Add to Plan button. This adds the
selected plan components in bulk to the plan list.

Incentive Management Admin Design Guide

88 PUBLIC About Plans
6.2 Creating a Plan

A plan includes a set of rules that specify how compensation is processed for each position that is assigned to
the plan. You can first create the rules and then create a plan, or you can create a plan and then add rules at the
same time.

Procedure

1. Navigate to Plan Data > Plans Wizard.

2. Choose Create in the toolbar.
3. Select the Calendar from the drop-down.
4. Set the Effective From and Through dates.
5. Choose OK.
6. Fill out all required fields.
7. Choose Save.

Incentive Management Admin Design Guide

About Plans PUBLIC 89
Related Information

About Plans [page 87]

Adding Rules to a Plan [page 90]

6.3 Adding Rules to a Plan

Rules can be shared across plans. In other words, the same rule can be used in multiple plans.

 Note

The system does not prevent you from creating circular self-references across rules in a plan, but
you should not do so. For example, within the same plan, MeasurementA references MeasurementB,
and MeasurementB references MeasurementA.

1. Choose Plans Wizard from the menu.

2. Search for the plan to which you want to add rules.
3. Choose Edit .
4. Choose Add Existing Rule specific to the type of rule (credit, measurement, incentive, or deposit)
to be added or create a new rule using the Create New Rule option. If business units are
implemented, the business unit or units assigned to the plan are automatically assigned to the new rule.

Specify the rule name. You can find and select a rule using wildcard matching, auto-matching, or the
Search field. If business units are implemented, only rules that have one or more business units in
common with the plan are displayed. For example, you cannot add a rule that is assigned to only the
EMEA business unit to a plan that is assigned to only the North America business unit. However, if the
plan includes both the EMEA and North America business units, a rule that is assigned to only the EMEA
business unit can be added. Also, only rules of the type being added are displayed. For example, if you are
adding a credit rule and you use the Search field button, you do not need to enter search criteria to restrict
the search to just credit rules. The Select a Rule dialog automatically displays only credit rules.
5. Choose Add to Plan and Save. The rule name and description, if any, display in the Rules area.
6. Continue to add rules.

Incentive Management Admin Design Guide

90 PUBLIC About Plans
7. Choose Save to save the plan.

Related Articles

• Assigning a Plan by Title [page 91]

• Assigning a Plan to a Specific Position [page 92]

6.4 Plan Assignments

You can assign a plan by title, or to a specific position. Plan assignment by title is recommended. When viewing
the Plan Summary for the plan, if a plan is assigned to a specific position, the position name is listed. If the plan
is assigned by title, the title name is listed.

Related Articles

• Assigning a Plan by Title [page 91]

• Assigning a Plan to a Specific Position [page 92]

6.4.1 Assigning a Plan by Title

As previously mentioned, plan assignment by title is the recommended method for assigning plans. When you
assign a plan to a title, the system automatically assigns all positions with that title to the specified plan. You
can override the title plan assignment by assigning the plan to a specific position.

Procedure

1. Navigate to Organization > Titles.

2. Search for the plan to which you want to assign a title.
3. Select the title to which you want to assign a plan in the Title Summary pane.
4. Choose Edit and search and select a plan from the field Plan. Specify the plan to be assigned to the title.
5. Choose Save.

When you next view the plan from the Plans Wizard workspace, the plan assignment is displayed on the
Assignments tab.

Incentive Management Admin Design Guide

About Plans PUBLIC 91
6.4.2 Assigning a Plan to a Specific Position

When you assign a position to a compensation plan, you select an individual position from the Reporting
Structure. For performance reasons, you should avoid assigning a single position to its own plan. A position
with its own plan should be the exception. Too many individual plans can overpopulate the repository
with potentially redundant rules and thereby cause a degradation of calculation performance. Reusing
compensation plans wherever possible decrease the processing load and makes calculation processing faster.

Procedure

1. Navigate to Organization > Titles

2. Search for the plan to which to assign a title.
3. Select the position to which you want to assign a plan from the Summary panel. If a plan has been assigned
to the position by title, the plan name displays in the Plan field followed by the word '(Title)'.
4. Specify the plan to be assigned to the position in the Plan field.
5. Choose Save.

When you next view the plan from the Plans Wizard workspace, the plan assignment is displayed on the
Assignments tab.

6.5 Editing a Plan

To edit a plan involves any of the following operations:

• Rename the plan

• Add rules to the plan
• Remove rules from the plan
• Change the effective dates of the plan
• Add or remove rule element variable assignments at the plan level

 Note

You cannot change the plan’s calendar. You must instead create a new plan. Currently, the association
between a calendar and a plan cannot be broken or changed

When you edit a plan, you are editing a specific version of the plan. For example, say you have a Golf Rep Plan
that is effective from January 2008 to the End Of Time. If, however, in April 2008 you add a new rule to the
plan, it is important to know the effective dates of the change. If you need changes to be back-dated effective
as of January 2008, you should edit the current version of the plan (Choose Manage Version in the Plans Wizard
workspace). However, to make changes effective from April 2008 to the End Of Time, you should create a
new version of the plan and make the changes to that new version (Choose New Version in the Plans Wizard
workspace.).

Incentive Management Admin Design Guide

92 PUBLIC About Plans
If you have a plan that is no longer effective, you change the effective end date of the plan to the required date.
You do not do a delete operation if the plan was valid for any point in time. To remove a rule from a plan, you
must also remove the rule’s association with any other objects, such as:

• variables
• formulas
• fixed values
• territories
• rate tables
• lookup tables
• plans
• other rules

6.6 Deleting a Plan

You can delete a plan that was just created either manually or using import even if rules have been assigned to
the plan. You cannot delete a plan that has been assigned to either a position or a title without first removing
the plan assignment. Deleting a plan removes all versions of the plan object from the repository.

However, the audit log in the Audit Log workspace retains information on the actions performed on the plan
object, including its remove (delete) date, and information about the object itself.

 Note

To delete a particular version of a plan, use the Manage Version option.

6.7 Finding Objects Related to Plans

You can find data related to one or more selected plans by selecting the appropriate object option from the
Related Searchicon.

Procedure

1. Navigate to Plan Data > Plans Wizard.

2. Search for the plan or plans for which you want to find related data.
3. Select the plan or plans in the Summary panel.
4. Choose any object in the Related Search, for example, titles. If you are searching for related positions,
fixed values, rate tables, territories, or lookup tables, the objects are retrieved immediately and the results
are displayed in the related workspace. If no results are found, the message No Results Found displays. If
the object option selected was rules, variables, formulas, titles, or quotas, the Search For Related Objects
dialog displays with the name of the selected object substituted for the object name.

Incentive Management Admin Design Guide

About Plans PUBLIC 93
The available options and data returned are as follows:

• Rules: returns the rules associated with the selected plan.

• Variables: returns the variables directly referred to by the rules that belong to the plan. Does not return the
variables referred to by formulas that are used by rules belonging to the plan.
• Formulas: returns the formulas directly referred to by the rules of the selected plan.
• Titles: returns the titles referring to the selected plan.
• Positions: returns the positions directly referring to the selected plan. If the plan is assigned by title,
returns the position that is referring to the title that is assigned to this plan.
• Fixed Values: returns the following:

• Fixed values directly used in the rules belonging to the selected plan.
• Fixed values referred to by any other rule element used in rules that belong to the selected plan.
• Fixed values assigned to the fixed value variables that are assigned to the selected plan.

• Rate Tables: returns the following:

• Rate tables directly used in the rules belonging to the selected plan.
• Rate tables assigned to the rate table variables that are assigned to the selected plan.

• Territories: returns the following:

• Territories directly used in the rules belonging to the selected plan.

• Territories assigned to the rate table variables that are assigned to the selected plan.

• Lookup Tables: returns the lookup tables directly referred to by the rules of the selected plan. Does not
return the lookup tables referred to by formulas that are used by rules belonging to the plan.
• Quota: returns the quotas directly referenced by the rules of the selected plan.

6.8 Plan Components

Plan components are collections of rules grouped by business logic. They are maintained centrally in this
workspace. Components can also be imported or exported for re-use.

Related Articles

• Plan Components Workspace [page 95]

• Creating a Plan Component [page 95]
• Adding Rules to a Component [page 96]
• Adding a Component to a Plan [page 96]
• Editing a Component [page 97]
• Deleting a Component [page 98]
• Finding Objects Related to Components [page 98]

Incentive Management Admin Design Guide

94 PUBLIC About Plans
6.8.1 Plan Components Workspace

In the Plan Components workspace, you can create or edit components, copy components, add or remove
rules to or from components. You can also create rules dynamically in this workspace.

Navigate to Plan Data > Plan Components to access the Plan Components workspace.

Plan Component Details

The Plan Component Details section has two tabs:

• General Information - Contains information about the selected plan, and rules associated with it.
• Associations - Displays plan documents associated with the selected plan.

Related Information

Plan Components Workspace [page 95]

6.8.2 Creating a Plan Component

You can create a plan component, add rules to them or you can create a component and add it to a plan.

Procedure

1. Navigate to Plan Data > Plan Components.

2. Choose Create.

Incentive Management Admin Design Guide

About Plans PUBLIC 95
3. Select a different calendar and set effective dates
4. Choose Ok.
5. Enter a unique name for this component in the Plan Component Details section. The Summary panel
immediately reflects your entries.
6. (Optional) Type a description.
7. (Optional) Select a business unit.
8. Choose Save.

6.8.3 Adding Rules to a Component

Rules can be shared across components. In other words, the same rule can be used in multiple components.

Procedure

1. Navigate to Plan Data > Plan Components

2. Search for the component to which you want to add rules.
3. Choose Add Existing Rule and specific to the type of rule (credit, measurement, incentive, or deposit) to be
added. A data entry field for the rule name displays.
4. Specify the name to be added by doing one of the following in the rule name data entry field:
• Find and select a rule using the Search field button. If business units are implemented, only rules
that have one or more business units in common with the component are displayed. For example, you
cannot add a rule that is assigned to only the EMEA business unit to a component that is assigned to
only the North America business unit. However, if the component includes both the EMEA and North
America business units, a rule that is assigned to only the EMEA business unit can be added.
• Create a new rule using the Create New Rule button. If business units are implemented, the
business unit or units assigned to the component are automatically assigned to the new rule.
• Enter Save to save the rule on the component. The rule name and description, if any, display in the
Rules area.
5. Choose Save to save the component.

6.8.4 Adding a Component to a Plan

Components can be shared across plans. In other words, the same component can be used in multiple plans.

 Note

To delete a particular version of a plan, use the Manage Version option.

Incentive Management Admin Design Guide

96 PUBLIC About Plans
Procedure

1. Navigate to Plan Data > Plan Components.

2. Search for the plan to which you want to add a component.
3. Select Plan Components from the View by option list of the Plan Details panel.
4. Specify the name to be added by doing one of the following in the component name field:
• Find and select a component using the Search field. If business units are implemented, only
components that have one or more business units in common with the plan are displayed. For
example, you cannot add a component that is assigned to only the EMEA business unit to a Plan
that is assigned to only the North America business unit. However, if the plan includes both the EMEA
and North America business units, a component that is assigned to only the EMEA business unit can
be added.
• • Create a new component using the Add Plan Component New button. If business units are
implemented, the business unit or units assigned to the plan are automatically assigned to the
new component.
• Choose Save to save the component on the plan. The component name displays in the
Components area.
5. Continue to add components as needed.
6. Choose Saveto save the plan when all the components are added.

6.8.5 Editing a Component

Editing a component involves any of the following operations:

• Rename the component

• Add rules to the component
• Remove rules from the component
• Change the effective dates of the component
• Add or remove rule element variable assignments at the component level

 Note

You cannot change the component’s calendar. You must instead create a new component. Currently, the
association between a calendar and a component cannot be broken or changed.

When you edit a component, you are editing a specific version of the component. For example, say you have a
Golf Rep Component that is effective from January 2008 to the End Of Time. If, however, in April 2008 you add
a new rule to the component, it is important to know the effective dates of the change.

If you need changes to be back-dated effective as of January 2008, you should edit the current version of the
component, choose Manage Version in the Plans Wizard workspace. However, to make changes effective from
April 2008 to the End Of Time, you should create a new version of the component and make the changes to
that new version, choose Add New Version in the Plans Wizard workspace.

Incentive Management Admin Design Guide

About Plans PUBLIC 97
If you have a component that is no longer effective, you change the effective end date of the component to the
required date. You do not do a delete operation if the component was valid for any point in time. To remove a
rule from a component, you must also remove the rule’s association with any other objects, such as:

• variables
• formulas
• fixed values
• territories
• rate tables
• lookup tables
• plans
• other rules

6.8.6 Deleting a Component

You can delete a component which is not associated with any plan, even if rules have been assigned to it. You
cannot delete a component that has been assigned to any plan. Deleting a component removes all versions of
the component object from the system. However, the audit log in the Audit Log workspace retains information
on the actions performed on the component object, including its remove (delete) date, and information about
the object itself. .

 Note

To delete a particular version of a component, use the Manage Version in the Ellipsis Menu (…).

6.8.7 Finding Objects Related to Components

You can find data related to one or more components by selecting the appropriate object option from the
Related pane. The available options and the data returned are as follows:

Plans—returns the plans referred to by the selected component.

Rules—returns the rules referred to by the component.

Procedure

1. Choose Plan Data > Plan Components.

2. Search for the component or components for which you want to find related objects.
3. Select the component or components in the Summary panel.
4. Select an object option, for example, plans in the Related panel.

• If you are searching for related rules, the results are immediately retrieved and displayed in the Rules
Wizard workspace. If no results are found, the message No Records Found is displayed.

Incentive Management Admin Design Guide

98 PUBLIC About Plans
• If you are searching for related plans the objects are retrieved immediately and the results are displayed in
the related workspace. If no results are found, the message “No Records Found” is displayed.

6.8.8 Audit History for Plan Component Information

The Audit history provides the list of all of the changes that have been made to objects over time.

Plan Component Information in Audit History of Plans - Example

1. Choose Plan Data > Plan Components.

2. Create a plan component and assign rules to it.
3. Choose Plan Data > Plan Wizard .
4. Create a plan and assign to the plan component created in the step 2.
5. Choose the Audit History of plans option, in the Rules section of Plan Details. The Component section is
displayed.
6. Choose the Component section. It displays the already assigned list of plan components under the Plan
components section (Step 2).
7. When you choose the component under the list of plan components, it displays all the rule information of
that component for audit.

Incentive Management Admin Design Guide

About Plans PUBLIC 99
7 About Rules

A compensation rule is a combination of input, condition criteria, and an output result. You use compensation
plan rules to specify how the system calculates credits, measurements, incentives, and deposit amounts for
participants who are assigned to the plan. You can create and edit rules in the systen. You can also use XML
import to import your rules. Compensation rules are constructed by users to specify how the system handles
compensation processing for their own business requirements. Each compensation rule specifies the input to
a processing stage, condition criteria that must be met, and an action or actions to be taken if the condition is
met.

You write compensation rules using Boolean logic—logical statements whose conditions are evaluated as true
or false. (If a rule does not have a condition, then it always runs.) Typically the logic of a compensation rule
is an if condition, followed by a then action. If the condition is met (true), then the action is performed; if
the condition is not met (false), then no further action is taken for that rule for the position assignment
being evaluated during calculation processing. Each compensation rule is a set of statements that tells the
system what action(s) to perform when defined criteria are met in a specific calculation stage. Compensation
plan rules specify how the system calculates credits, measurements, incentives, and deposit amounts for
participants who are assigned to the plan when the calculation is run.

Compensation plan rules are created in the Rule Editor, where you define the input criteria, conditions under
which it is processed, and the action is taken when it is processed. The type of compensation rule corresponds
to a calculation stage: credit, primary measurement, secondary measurement, incentive, and deposit. Each
calculation stage runs the compensation rules for that stage. Compensation rules in the system are used
in compensation plans to calculate compensation. The system also uses classification rules to classify valid
transactions during the classification stage of the calculation.

 Note

Classification rules serve a different purpose than compensation rules.

Related Articles

• Rules Wizard Workspace [page 101]

• Rule Types [page 102]
• Rule Elements [page 103]
• Rule Conditions [page 104]
• Rule Actions [page 107]
• Multiple Actions in Rules Overview [page 105]
• Editing a Rule [page 107]
• Finding Objects Related to Rules [page 109]
• Working with Generic Attributes in Rules [page 110]
• Using Multiple Actions in Rules [page 112]
• Rules that Produce the Same Result [page 113]

Incentive Management Admin Design Guide

100 PUBLIC About Rules
• Rules in Compensation Plans [page 114]

7.1 Rules Wizard Workspace

In the Rules Wizard workspace, you can create, modify, copy, and delete rules.

The Rules Wizard workspace contains the General Information tab and the Associations tab.

The name and fields in the Rules Wizard workspace vary depending on the type of rule being created. Each of
the four rule types has a distinct editor.

Navigate to Plan Data > Rules Wizard to access the Rules Wizard workspace.

All rule editors have similar tabs. The actual display name of the tab depends on the type of compensation rule
(credit rule, measurement rule, incentive rule, or deposit rule) selected from the Type drop-down list.

Rule editors contain the same basic areas with some exceptions:

• Input and filter area: In the input area, you must specify the source of the rule. The source for credit rules
can be either transactions or orders; the source for measurement rules can be credit or other, and the
source for deposit rules can be incentives or deposits. Incentive rules do not take an input source type. In
the filters area, you can specify conditions.
• One or more action areas: The input to the rule that meets these conditions causes the actions defined
in the actions area. In the actions area, you must specify the actions or the actions that the rule should
execute when the rule conditions are met.

 Note

If Period Type is modified in an Incentive Rule, then all the versions will be updated with the new Period
Type. Changing the Period Type can impact the pipeline results if the output is shared.

Incentive Management Admin Design Guide

About Rules PUBLIC 101
Associations Tab

The following figure shows an example of the Associations tab in the Rules Wizard workspace. From this tab,
you can view the plans that contain the rule. You can also view inputs to the rule, the outputs from the rule, and
the rules that use the output from the rule.

7.2 Rule Types

The following table lists the different types of rules.

Basic Rule Type Description Rule sub-type

Credit Credit rules determine how credits • Rule Transaction Credit

are allocated to position assignments. • Rolled Transaction Credit
Credit rules tell the system which trans- • Direct Order Credit
actions or rolled credits are to be op- • Rolled Order Creit
erated on by a compensation plan,
and therefore which credits to con-
sider when calculating compensation
for each position assignment under
that plan.

Primary Measurement Primary measurement rules aggregate Primary Measurement

the credits for position assignments.

This typically means to sum the mone-
tary value of credits. However, you can
also define measurement rules to ag-
gregate credits in other ways, such as
by different product lines and by count-
ing the number of units sold.

Incentive Management Admin Design Guide

102 PUBLIC About Rules
Basic Rule Type Description Rule sub-type

Secondary Measurement Secondary measurement rules aggre- Secondary Measurement Rul

gate primary measurements or perform
calculations based on formulas or other
values.

Incentive Incentive rules calculate the incentive • Incentive Rule

compensation for each position assign- • Commission Incentive Rule
ment assigned to the compensation
plan. Typically, when the system proc-
esses an incentive rule, it compares
measurements to attainment targets
such as quotas for each position as-
signment.

Deposit Deposit rules specify which incentives • Deposit Rule

to pay, and • Detail Deposit Rule
when or if to pay them. If deposits need
to be held back for any reason, such as
for unpaid customer invoices or maxi-
mum earning policies for a product, you
can indicate in the deposit rule that the
deposit is held and for how long.

7.3 Rule Elements

To increase flexibility, you can structure your compensation rules to reference rule elements instead of
specifying values within the rule. Rule elements are stored independently of the rule and can be used in
multiple rules. You can also include one rule element in another. For example, you can write a formula that
references a rate table or includes a formula in a rate table. The following table lists the kinds of rule elements.

Kinds of Rule Elements

Rule Description

Fixed value A numeric quantity used to represent an amount. Used to

store static numeric values for use in different rules. You can
specify fixed values to apply only to a specified period. You
can use fixed values for a number of purposes, including
quotas, target bonus amounts, commission rates, or Boo-
lean (true/false) information.

Incentive Management Admin Design Guide

About Rules PUBLIC 103
Rule Description

Formula The mathematical expression used to calculate a value. For-

mulas return a value with an associated unit type.

Lookup table The multi-dimensional table used to store a set of values

for use in rules and formulas. Compare with the rate table,
which is for a specific purpose and contains only two dimen-
sions- rates and tier levels.

Quota Values that apply across an entire reporting structure, and

you can manage the different values from a single screen.
You can select multiple period types, and perform automatic
sum or distribute functions to distribute the quota values
across an organization.

Rate table Defines different rates across rate thresholds or tiers. Used
to calculate incentive compensation for a step commission.

Territory Combination of criteria, based on categories and classifiers.

Used in credit or primary measurement rules to determine
who gets credit for a transaction, and in secondary measure-
ment, rules to determine how credits are aggregated.

Variable Use as a placeholder in rules, formulas, and lookup tables to

reference a fixed value, rate table, or territory. Variables can
be used anywhere these types of rule elements can be used
and you can assign different values for each variable in the
plan, title, or position level.

From the Plan Wizard workspace, you can also assign rule elements to variables. You can create rules either
from a plan or from the Rules Wizard workspace.

7.4 Rule Conditions

A condition is a set of criteria that must be met before an action can occur. Use conditions to specify when the
system should process a rule. In the Condition field, legal moves operates in the same way as when creating
formulas. However, the construction of the conditional criteria differs somewhat from how you build formulas.
To include a formula as part of a condition, you should do one of the following:

Using a Formula in the Condition of a Rule

1. List the formula first. For example,

• Formula1 > 1 AND DataCondition = TRUE

Incentive Management Admin Design Guide

104 PUBLIC About Rules
2. Put the formula inside of parentheses. For example:
• Formula1 > 1 AND DataCondition = TRUE
3. Embed the formula within a function. For example:
• DataCondition = TRUE AND ABS(Formula1) > 1= TRUE. Otherwise, the formula is not available in the
legal moves listing.

Null Comparisons in Rule Conditions

In the condition of a compensation rule, a “not equals? compared to a value that is null causes the system to
not process the rule. For example, Participant.Attribute 9 <> “bronze? The rule is not processed, because null
is not a true value, it is the absence of a value. To cause the system to run the rule, the condition should include
a condition for null cases. For example, Participant.Attribute 9 <> “bronze? AND Is Null (Participant.Attribute
9) = false

7.5 Overview: Multiple Actions in Rules

If you are using multiple actions in some of your secondary measurement, incentive, commission, or deposit
rules, it is very important that you be aware of how the system processes rules in order of dependency. The
system determines the dependency at the rule level, not at the action level. If you have multiple actions in some
of your rules, all of these actions must be at the same dependency level, or you get incorrect results. As part
of pre-processing for the Reward stage, the system determines the dependencies of all Reward stage rules.
These dependencies determine in what order the system processes the rules so that the dependencies are
appropriately satisfied.

For example, an incentive rule can depend on the output of another incentive rule, and that rule can depend on
the output of a secondary measurement rule, and the secondary measurement rule can depend on the output
of a primary measurement rule.

During the Reward stage pre-processing, the sytsem calculates the dependency so that the rule at the
bottom of the dependency chain is processed first, and then the rules are processed in order of successive
dependency. During the Reward stage, the system processes all level 0 rules first (or evaluates them to
determine that they are not processed). This occurs before the system processes any Level 1 rules. After the
Level 0 rules have all been evaluated and run, then the system evaluates and processes just the Level 1 rules,
and so on through all the dependency levels.

Incentive Management Admin Design Guide

About Rules PUBLIC 105
The system assigns each item in a rule dependency chain a dependency level. In the previous example, the
Secondary MeasurementA would be assigned a level 0, as long as it does not depend on any other secondary
measurements. The IncentiveA would be assigned a level 1, and the IncentiveB would be level 2.

 Note

You can see the dependency levels listed in the Reward stage log file if you run the calculation in Internal
mode.

It is very important to understand that the sytsem calculates the rule dependencies at the rule level, and not
at the action level. If a rule contains multiple actions that have various dependency levels, the system gives
the rule the same level as the highest level of action. For example, if the first action of an Incentive rule was
the Incentive B from the previous example, its dependency level would be 2. If there was another action in this
same rule that simply depended on a Secondary Measurement (which, in turn, had no dependencies), it would
be at level 0. However, because the dependencies are computed at the rule level and not at the action level, the
entire rule is set at a dependency level of 2. This effectively bumps the second action in this rule from level 0 to
level 2 (to match the level of the highest level action in the rule).

Because of rule dependency levels, there are certain guidelines that you must follow if you choose to create
multiple actions in rules:

• Be sure that all actions in a rule are of the same dependency level. If in doubt, put the action in a separate
rule.
• Never put an action in a rule that depends on another action in the same rule.

 Note

A secondary measurement rule that references a primary measurement and no other result object has a
dependency level of zero

Incentive Management Admin Design Guide

106 PUBLIC About Rules
During processing, the system processes each type of rule independently and in order of calculation
processing. This means that the system processes all secondary measurement rules before it processes any
incentive rules, and it processes all incentive rules before processing any deposit rules.

 Note

A secondary measurement that references a primary measurement and no other result object, is at level
0. From the perspective of the Reward stage, there are no dependencies on Allocate stage objects (primary
measurements), because all primary measurements are already calculated when you get to the Reward
stage.

7.5.1 Rule Actions: Reportable Flag and Display Name of

Reports

To export the Reportable Flag and Display name of the Report, in the Rules Wizard workspace, choose the
Export Data icon to perform an XML export. You can find the Reportable Flag and Display name of the Reports
in the exported/downloaded XML file.

 Note

When the XML file is downloaded, the Unit Type of the rule may display as a currency (for example, generic
“ARS” value) in the file, but this value does not impact the calculations or the import process in any
manner.

Each rule contains one or more actions. When rules are evaluated during calculation processing, actions are
executed to produce an output. See Overview: Multiple Actions in Rules [page 105] for details.

7.6 Overview: Editing a Rule

To edit a rule involves any of the following operations:

• Rename the rule

• Add or remove a rule element (formula, variable, fixed value, rate table, territory, or lookup table)
• Add or remove a condition
• Change the input to a rule
• Rename the rule’s output
• Add, remove, or change any of the actions of a rule that contribute to how the rule calculates its results
• Change the effective dates of the rule

The following table lists the restrictions that must be observed when editing rules.

Incentive Management Admin Design Guide

About Rules PUBLIC 107
Restrictions on Editing Rules

Rule Type(s) Restrictions

All rule types You cannot change the calendar of a rule. You must instead
create a new rule. Currently, the association between a cal-
endar and a rule cannot be broken or changed.

Incentive and measurement rules All versions of an incentive and measurement rules must
have the same output period type and unit type. Do not
change the output period type or unit type. Instead, create a
new incentive rule with the required output period and unit
type.

Be aware that when you edit a rule, you edit the specified version of the rule. For example, say you have a
rule that is effective from March 2008 to the End Of Time. If, however, in May 2008 you change how the rule
calculates the credit, it is important to know the effective dates of the change. If, for example, your changes are
to be back-dated effective to March 2008, then you edit the current version of the rule (click Manage Versions
in the Rules Wizard workspace). However, if, your changes are to be effective from May 2008 to the End Of
Time, then you create a new version of the plan and make the changes to that new version (click New Version in
the Rules Wizard workspace). If you have a rule that is no longer effective, you change the effective end date of
the rule to the required date. You do not do a delete operation if the rule was valid for any point in time. When
you go to edit a rule, the system displays a message that tells you the plans that the selected rule is assigned
to; any change to this rule affects all plans the rule is assigned to.

Related Articles

• Renaming a Compensation Rule [page 108]

• Deleting a Rule [page 109]

7.6.1 Renaming a Compensation Rule

You can rename a rule. When you rename a rule, the rule’s output name does not change, unless you directly
change the output name as well.

Related Information

Rules Wizard Workspace [page 101]

Incentive Management Admin Design Guide

108 PUBLIC About Rules
7.6.2 Deleting a Rule

You can delete a rule that does not have any related results data (a calculation run has not yet occurred for the
associated plan and position). For example, you can delete a rule that was just created either manually or using
import, even if the rule refers to other rule elements. You can also select rules of different types (credit rules,
measurement rules, incentive rules, and deposit rules) and delete them if the rules selected do not have related
results data. When you multi-select rules of different types, no information is displayed in the detail pane.

You cannot delete a rule if it has associated results data. For example, you cannot delete a measurement or
incentive rule if Create Default Data has been run, because Create Default Data creates empty placeholder
objects for these rules. You cannot delete a rule if it is referenced by a plan. You should consider end dating it
instead.

Deleting a rule removes all versions of the rule object from the the system. However, the audit log in the Audit
Log workspace retains information on the actions performed on the rule object, including its remove (delete)
date, and information about the object itself.

 Note

To delete a particular version of a rule, use the Manage Versions option in the Ellipsis Menu (…).

Related Information

Rules Wizard Workspace [page 101]

7.7 Finding Objects Related to Rules

You can find data related to one or more rules. Specifically, you can find data related to the following objects:

• Plans: returns the plans referring to the selected rule.

• Variables: returns the variables directly referred to by the selected rule. Does not return the variables
referred to by formulas that are used in the rule.
• Formulas: returns the formulas directly referred to by the selected rule.
• Territories: returns the territories directly referred to by the selected rule.
• Fixed Values: returns the fixed values directly referred to by the selected rule.
• Rate Tables: returns the rate tables directly referred to by the selected rule.
• Lookup Tables: returns the lookup tables directly referred to by the selected rule.
• Quotas: returns the quotas directly referred to by the selected rule. the plans referring to the selected rule.

Incentive Management Admin Design Guide

About Rules PUBLIC 109
Procedure

1. Choose Plan Data > Rules.

2. Search for the rule or rules for which you want to find related data.
3. Choose any object in Related search, for example, plans.

The Search for Related search dialog displays with the name of the selected object substituted for the object
name.

Related Information

Rules Wizard Workspace [page 101]

7.8 Overview: Generic Attribute

If generic attributes are enabled, you can use those attributes when creating rules. The following table lists the
types of rules on which generic attributes can be used and the specific attributes that must be enabled in the
Customization workspace so that they can be used.

 Note

Generic attributes cannot be used in primary measurement, commission incentive, and detail deposit
rules.

Rules Supporting Generic Attributes

Type of Rule Controlling Attribute in the Customization Workspace

Direct transaction credit Results > Transactions

Rolled transaction credit Results > Transactions

Direct order credit Results > Credits

Rolled order credit Results > Credits

Primary measurement N/A

Secondary measurement Results > Measurements

Incentive Results > Incentives

Incentive Management Admin Design Guide

110 PUBLIC About Rules
Type of Rule Controlling Attribute in the Customization Workspace

Commission incentive N/A

Deposit (incentive-based) Deposits

Detail deposit (credit-based) N/A

Related Articles

• Using Generic Attributes in Rules [page 111]

• Example: Generic Attributes on Credit Rules [page 112]

7.8.1 Using Generic Attributes in Rules

Generic attributes can be used in calculations and included for reporting purposes in some rules. Generic
attributes can be included for reporting purposes only in other rules.

Generic Attributes in Calculations

Transaction and credit generic attributes can be used in calculations:

• Transaction Generic Attributes - Can be used in direct transaction credit and rolled transaction credit
rules. For example, you can include generic attributes, such as Transaction.Generic Attribute 1, in the
conditions and actions of these rules. You can also use transaction generic attributes in all other rule types
that have access to the Credit.Transaction.* andSource Credit.Transaction.* attributes.

• Credit Generic Attributes - Can be used in primary measurement and commission incentive rules. For
example, you can include generic attributes, such as Credit.Generic Attribute 1, in the conditions and
actions of these rules. The values for credit generic attributes are generated by the credit rule actions.
These attributes are populated when the calculation is run and credits are generated.

Generic Attributes for Reporting

A common use of generic attributes is for reporting only purposes. For example, if the output amount of a
credit rule is based on a calculation, you can store the components of the calculation in a generic attribute.
As previously mentioned, transaction and credit generic attributes can be used in calculations as well as for

Incentive Management Admin Design Guide

About Rules PUBLIC 111
reporting only purposes. In addition, measurement, incentive, and deposit generic attributes can also be used
for reporting only purposes:

• Measurement generic attributes - Can be included in secondary measurement rules. The values for
measurement generic attributes are generated by secondary measurement rule actions. These attributes
are populated when the calculation is run and secondary measurements are generated.
• Incentive generic attributes - Can be included in incentive rules. The values for incentive generic
attributes are generated by incentive rule actions. These attributes are populated when the calculation
is run and incentives are generated.
• Deposit generic attributes - Can be included in incentive-based, detail deposit rules. The values for
deposit generic attributes are generated by deposit rule actions. These attributes are populated when the
calculation is run and deposits are generated.

7.8.2 Example: Generic Attributes on Credit Rules

The following figure shows an example of a rolled transaction credit rule with transaction generic attributes
enabled. Click on the plus ( ) to expand each type of generic attribute available.

7.9 Multiple Actions In Rules: Implications

When dealing with various actions in secondary measurement, incentive, commission, or deposit rules,
it becomes crucial to understand the system's rule processing order based on dependency. The system
determines dependencies at the rule level, rather than the individual action level. Hence, if you have multiple
actions within a rule, it is essential to ensure that all these actions are at the same dependency level; otherwise,
incorrect outcomes may arise.

Related Articles

• Overview: Multiple Actions in Rules [page 105]

Incentive Management Admin Design Guide

112 PUBLIC About Rules
• Implications of Inappropriate Multi-Actions Rules [page 113]

7.9.1 Implications of Inappropriate Multi-Actions Rules

If you put an action in a rule that depends on another action in the same rule, this can cause incorrect results.
The errors might or might not result in errors produced in the log file, such as circular reference issues. For
example, if ActionA depends upon ActionB, ActionA must be at a higher dependency level than ActionB to
get the correct answer. But, because both actions are in the same rule, they both have the same dependency
level (that of ActionA). This (in the worst case) leads to strange self-dependency issues and possible circular
references errors. In the best case, it causes random results; because within a given dependency level the rule
firings are essentially random. That means that in some calculation runs ActionB fires before ActionA. But in
other runs, ActionA could fire before ActionB, leading to incorrect results.

 Note

The system prevents you from creating circular self-references within the same rule. For example, a
circular reference is if you use the output of a rule to calculate the output of the same rule, such as rule
output name=IncentiveA and you use IncentiveA to calculate the incentive. (This is different from referring
to the output of one action in a rule from another action in the same rule. This form of self-reference is
allowed).

If a rule depends on the results of one or more actions in a multi-action rule, the system does not process
the rules in the correct order. For example, if a multi-action rule has an action with a level 2 dependency and
another action with a level 0 dependency, the level 0 action gets bumped to level 2. If there is another rule with
a level 1 dependency that depends on the output of the action with a level 0 dependency, that level 1 rule will
have an incorrect result. In addition, all rules that depend on the level 1 rule will also have incorrect results.

7.10 Rules that Produce the Same Results

It is possible to create multiple rules that produce results with the same output name. For example, if you
have overwritten the default output name, which is normally the same as the rule name, it is possible to have
two incentive rules, "Incentive Rule 1" and "Incentive Rule 2", that both produce an incentive output named
"Year-End Bonus." If multiple rules produce the same named output, it is imperative that these rules have
mutually exclusive conditions that guarantee that only one of these rules be processed during a calculation run.
If these rules do not have mutually exclusive conditions, and as a result, more than one rule is processed, the
output from the second rule overwrites the output from the first rule, the output from the third rule overwrites
the output from the second rule, and so forth. There is no way to guarantee the order in which the rules are
processed. Thus, these rules can result in indeterminate and inconsistent calculation results.

An interesting derivation of this scenario is presented by commission rules. A commission rule with a condition
processes every eligible credit. For all other rules, the condition is evaluated only once, and the result
determines if the rule is processed during a calculation run. A commission rule is an exception because the
condition is not applied to the rule as a whole, but rather to each of the credits that are evaluated in the
(per-credit) commission process. This means that mutual exclusivity must now be enforced not only at the
rule level but also at the credit level. In other words, if one or more of the rules that creates an identically

Incentive Management Admin Design Guide

About Rules PUBLIC 113
named output is a commission rule, the condition on that rule must be such that it is impossible for even
a single credit to satisfy that condition if another rule (or credit evaluation in another commission rule) can
produce the same named output during a calculation run. Because a single rule can only have one condition
and that condition applies equally to each rule action, it would be impossible to make multiple actions (from
the same rule) mutually exclusive. Thus creating multiple actions with the same output within a single rule is
not supported.

7.11 Rules in Compensation Plans

Compensation plans are usually composed of five types of rules: credit, primary measurement, secondary
measurement, incentive, and deposit. A plan generally contains one or more of each of these rule types;
each rule type drives a different processing stage in the calculation. You can create compensation rules
independently of a plan in the Rules Wizard workspace. You can add the same rule to multiple plans; this is the
concept of shared rules. If you update a shared rule, the rule is updated in each plan where it is used. All rules
on a plan must be associated with the same calendar as the calendar associated with the plan.

Rules and plans are effectively dated. Changing a rule in an existing plan changes the version of the plan as
well as the version of the rule. You can assign a plan to one calendar only. To use a formulaic expression in one
rule, just enter the expression in the rule’s condition, filter, or calculation/output fields. To reuse the formulaic
expression in other rules or rule elements, save it as a formula. Generally, you should create each rule in order
of processing - credit, primary measurement, secondary measurement, incentive, deposit - because you are
often prompted to select named input from a previous rule as you create the next rule. All rules on a plan
must correspond to the same calendar as the one to which the plan is assigned. You can assign a plan to one
calendar only. Rules and plans have effective times. When you change a rule in an existing plan, a new version
of the plan is created as well as a new version of the rule.

 Note

Some compensation plans might not require all five types of compensation rules. For example, you might
not need credit rules in a plan that uses only imported credits.

Incentive Management Admin Design Guide

114 PUBLIC About Rules
8 Classification Data:Overview

Classification data is a type of reference data. It is used to group or classify sales transactions. Classification
data includes categories and classifiers, and is organized into category hierarchies that do the following:

• Identify the individual products or services your company sells (classifiers).

• Identify the product or service lines your company offers (category hierarchies, categories, and
subcategories within categories).
• Assign classfiers to categories which includes associating classifiers (products or services) to categories
(product or service lines) for a given period of time.
• Identify unassigned classifiers. Unassigned classifiers are classifiers that are assigned to a classifier type
but are not associated to a category hierarchy.

The following figure shows a typical category hierarchy and its categories, subcategories, and classifiers.

The classification data workspaces are accessible from Plan Data > Classifications. It includes the categories
workspace, workspaces for the pre-defined classifier types (Products, Customers, and Postal Codes), and any
other workspaces based on the classifier types defined by the administrator.

Category hierarchies can be created from the bottom up, starting with creating classifiers, or from the top
down, starting with creating category hierarchies. However, the general activities required to create category

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 115
hierarchies and associated classification rules, categories and sub-categories, and classifiers and classifier
types are as follows:

1. Identify the transaction data to be used to match against classifiers in the category hierarchy. This includes
all information used by your company to determine how revenue is credited for sales.
• For example, if your company allocates credits based on product, you would identify the product
information found on the transaction. If your company allocates credits based on postal code, you
would identify the postal code information found on the transaction. If your company allocates credits
based on customer, you would identify the customer information found on the transaction.
2. Create user-defined classifier types if necessary.
• The system provides three predefined classifier types Product, Customer, and Postal Codes. The
administrator can create additional user-defined classifier types that you need by making entries in the
Customization workspace.
3. Create category hierarchies, categories, and classifiers.
• For example, create a Product category hierarchy with classifiers of the Product classifier type to filter
for transactions that contain specific product information. Create a Postal category hierarchy with
classifiers of the Postal Code type.
4. Create classification rules for each category hierarchy.

Related Information

Working With Categories [page 120]

Working With Classifiers [page 129]
About Category Hierarchies [page 125]
Category Hierarchy and Category Effective Dates [page 129]

8.1 Classification Data Workspaces

The Plan Data > Classification workspace contains the Category tab and the Classifiers tab.

• The Category tab lists Categories of all the Classifier Types. See Categories Workspace [page 117] and
Working With Categories [page 120] for details.
• The Classifiers tab provides a hierarchical view (tree view) of the selected Classifier Type. See Classifiers
Workspace [page 118] and Working With Classifiers [page 129] for details.

 Note

If you do not have Read permissions to Categories, the tree view is not available in any of the
classification data workspaces.

Incentive Management Admin Design Guide

116 PUBLIC Classification Data:Overview
8.2 Categories Workspace

The Categories tab is displayed by default on choosing Plan Data > Classifications. The Categories tab displays
category information in a list view and enables you to perform various functions to create and manage
categories. You can add, modify, and delete categories. You can also export and import Generic classifiers
via excel in this workspace.

Select a Category to view the Category Details page. The Category Details page enables you to update category
information and related data.

You can perform the following actions using the respective icons available in the tool bar and in the Ellipsis
Menu (…).

Action Description

Search Use the Search icon to perform a basic search. Search is

conducted across all the fields within the table and matching
records are returned.

Create Choose Create to create a new category. See Creating a

Category [page 121] for details.

Duplicate To copy a category, you must first select the category you
want to copy and then choose the Duplicate option. The
name of new category is prefixed with Copy of, which you
can update as needed.

Delete Use Delete to delete a selected category. You can select

multiple categories to delete. See Deleting a Category [page
124] for details.

Manage Version You can create new versions and edit existing versions using
the Manage Version option. See Object Versions Overview
[page 45] for details.

Related Search Related Search allows you to navigate from the Categories
workspace to other associated workspaces such as Classifi-
ers, Parent Category, Plan, Rules, and so on. See Related
Search Overview [page 58] for details.

Audit Audit History displays a quick summary of the updates made

to a category. Viewing Audit History of an Object [page 44]
for details.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 117
Action Description

Download Excel Data You can download the category template or data for the se-
lected records. Choose Download Excel Data and select the
appropriate option.

Upload Excel Data Choose Upload Excel Data and select the excel file to upload
data to the workspace.

Export Data Choose Export Data to export the selected categories to a

CSV or Excel file. You can specify the export options in the
Export to CSV dialog.

Configure Summary View Choose Configure Summary View to choose which fields
should display in the summary (list) view. Mandatory fields
are indicated with * and they cannot be removed (moved to
Available Fields). Only optional fields can be moved. You can
also drag and drop the fields to change the order.

Related Information

Working With Categories [page 120]

Working With Classifiers [page 129]

8.3 Classifiers Workspace

The Classifiers workspace provides a hierarchical view of the Classifiers and the Categories for a selected
Classifier Type. This workspace displays details of the predefined classifier types (products, customers, postal
codes) and the additional classifier types as defined the administrator administrator.

Select the Plan Data > Classifications > Classifiers tab to view the classifiers workspace. In this view (when
nothing is selected), you can choose a Classifier Type, Create a Category Hierarchy, or Create an Unassigned
Classifier.

Incentive Management Admin Design Guide

118 PUBLIC Classification Data:Overview
• Once you select a Classifier Type, you can further select (drill down) to view Categories, Sub-categories,
and Classifiers that exist within the selected Classifier Type. As you drill down, navigation links are formed
in the left panel that enable you to navigate back and forth the selected objects.
• The Create button in the left panel is dynamic depending on the object selected and allows you to create
only relevant objects. For example, when you select a Classifier Type, the Create button allows you to
create a Category Hierarchy. You can create Category Hierarchies, Categories, and Sub-categories in the
left panel.
• The list view in the right pane is dynamic and changes depending on the selected navigation link. For
example, if you select a category hierarchy, the list displays category hierarchies that exist in the Classifier
Type; if you select a category, the list displays all associated categories; and if you select a classifier, the list
displays all associated classifiers. Use the expand/collapse icon to view or hide details.

The following image illustrates a hierarchy view in the Classifiers tab.

You can perform the following actions using the respective icons available in the tool bar and in the Ellipsis
Menu (…). Only relevant icons are enabled when an object in the hierarchy view is selected.

Action Description

Search Use the Search icon to perform a basic search. Search is

conducted across all the fields within the table and matching
records are returned.

Create Click the Create to create a Classifier. See Creating a Classi-

fier [page 130] for details.

Duplicate To copy an object, you must first select the object you want
to copy and then choose Duplicate.

Edit You can use Edit to edit a Category Hierarchy or Category

depending on your section in the hierarchy. To update Classi-
fier information, choose a classifier and edit the information
in the details page.

Bulk Edit Use the Bulk Edit option, to update multiple Classifiers in one
go. The Bulk Edit button is enabled only when multiple Clas-
sifiers are selected. See Editing Multiple Classifiers (Bulk
Edit) [page 133] for details.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 119
Action Description

Delete Use Delete to delete a selected record. You can select multi-
ple objects to delete.

Manage Version You can create new versions and edit existing versions using
the Manage Version option. See Object Versions Overview
[page 45] for details.

Related Search Related Search allows you to navigate to other associated

workspaces such as Classifiers, Parent Category, Plan,
Rules, Territories, and so on. See Related Search Overview
[page 58] for details.

Audit Audit History displays a quick summary of the updates made

to an object. Viewing Audit History of an Object [page 44] for
details.

Download Excel Data You can download the template or data for the selected re-
cords. Click Download Excel Data and select the appropriate
option.

You can also download all the Classifiers using the Download
All Classifiers option.

Upload Excel Data Click Upload Excel Data and select the excel file to upload
data to the workspace.

Export Data Click Export Data to export the selected categories to a CSV
file. You can specify the export options in the Export to CSV
dialog.

 Note

If you do not have read permissions to Categories, the tree view option is not available to you. The
products, customers, postal codes, and other workspaces associated with user-defined classifier types
display information only specific to their Classifier Type.

Related Information

Working With Classifiers [page 129]

Working With Categories [page 120]
Creating a Category [page 121]
Creating a Classifier [page 130]
About Category Hierarchies [page 125]

8.4 Working With Categories

Categories are nodes within a category hierarchy. You can nest categories to create a hierarchy of
subcategories. The system allows you to create as many categories as you need. Classifiers can be assigned

Incentive Management Admin Design Guide

120 PUBLIC Classification Data:Overview
to categories and subcategories. As a best practice, you should create efficient categories so that when you
create your territories, which use categories and classifiers, you do not need to build complex expressions. This
results in more efficient processing. Categories can also be imported.

Related Articles

• Creating a Category [page 121]

• Moving a Category [page 124]
• Deleting a Category [page 124]

8.4.1 Creating a Category

You can create categories and add them to category hierarchies and other categories to create a nested
hierarchy of subcategories. You can create as many subcategories as you need. You cannot create categories
with duplicate names within the same category hierarchy. However, you can create categories with the same
name in different category hierarchies as long as the combination of the category hierarchy, and the category is
unique (effective dates or related classifier types differ).

The following tables provide examples of disallowed category names and effective dates, and examples of
allowed category names and effective dates.

Creating a Category in the Categories Workspace

1. Choose Plan Data > Classification > Categories tab.

2. ChooseCreate
3. Enter a name for the new category in the Name field in the detail pane.
4. Enter a description.
5. Select the appropriate Category Hierarchy.
6. (Optional) Assign Business Unit.
7. Choose Save.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 121
Creating a Category Hierarchy or Category in the Classifiers Workspace

1. Choose Plan Data > Classification > Classifiers tab.

2. ChooseCreate.
3. In Category Type, select Category Hierarchy or Category and choose Next.
4. In Insert Data, provide the required details. If you are adding a category directly under the category
hierarchy, the system automatically fill in the Category Hierarchy name and leaves the Parent Category
field blank. When you add a subcategory below another category, the system automatically fill in both the
category hierarchy name and the parent category. You normally do not need to change the data in these
fields (an exception is moving a category). If your organization has created and implemented business
units, you can assign this classifier to a business unit by selecting from the Business Units dropdown. You
can only select business units to which you as a user have been assigned. If one or more business units
have been assigned to the parent category hierarchy or category, the category inherits those assignments.
You cannot assign business units that have not also been assigned to the parent category or category
hierarchy.
5. ChooseNext.
6. Review the updates and choose Submit.

Incentive Management Admin Design Guide

122 PUBLIC Classification Data:Overview
Disallowed Category Hierarchy Names

Category Hierarchy Category Name Classifier Type Effective Dates

Cat Hierarchy A Category A Product Jan 2008 to EOT

Cat Hierarchy A Category A Customer Jan 2008 to EOT

Operator Description Classifier Type Effective Dates

Product
Cat Hierarchy A Category A Jan 2008 to Mar 2008

Product
Cat Hierarchy B Category A Jan 2008 to Mar 2008

Customer
Cat Hierarchy A Category A Apr 2008 to June 2008

Product
Cat Hierarchy A Category A Jul 2008 to Sept 2008

Related Information

Working With Categories [page 120]

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 123
8.4.2 Moving a Category
You can move a category to a different place in the same category hierarchy. You can also move a category to a
different category hierarchy if the destination category hierarchy has the same classifier type as the source.

Procedure

1. Choose Plan Data > Classification.

2. In the Categories or Classifiers tab, find and click on the category you want to move. Then use the Edit
option.
3. Select the name of the new Parent Category in the parent category field. You can also delete the parent
category. The category then moves to the top of the category hierarchy.
4. Choose Save.

8.4.3 Deleting a Category

You can delete a category that is not referenced in a rule. For example, you can delete a category that was
just created either manually or using import. When you delete a category, the warning “Are you sure you want
to delete this category and remove its associated relationship with classifiers” is displayed. If you click Yes,
the category and the subcategories under it (if any) are deleted. Classifiers associated with the category and
subcategories are not deleted, but they are disassociated (removed). Deleting a category removes all versions
of the category and subcategory objects from the system.

However, the audit log in the Audit Log workspace retains information on the actions performed on the objects,
including their remove (delete) date, and information about the objects themselves.

Incentive Management Admin Design Guide

124 PUBLIC Classification Data:Overview
  Note

To delete a particular version of a category, use the Manage Versions option in the Ellipsis Menu (…).

8.4.4 About Category Hierarchies

You can create category hierarchies and their respective classification rules in Plan Data > Classification >
Classifiers tab. The category hierarchy name represents the top node, also called the root, of the category
hierarchy structure. Category hierarchies can be created by doing the following:

• Naming the category hierarchy, such as Golf Sets.

• Specifying the classifier type. The predefined classifier types are a product, customer, and postal code. If
you have created user-defined classifier types, you can also choose them.
• Creating a classification rule that states the conditions for a match between each sales transaction and the
classifiers associated with the category hierarchy. For example, a sales transaction record for a profession
driver, PD688, would be matched against the classifier PD688 on the category hierarchy.
• Adding categories such as Golf Sets and Individual Clubs, and subcategories such as Pro Sets and Putters.
• Identifying each of the classifiers (leaf level attached to this structure, such as PP478 under Professional
Putter.

Category hierarchies can be simple (with one or two levels) or complex (with many levels), depending on the
complexity of the transaction data that is meaningful to your organization. A category hierarchy can also be a
simple list of classifiers under a category. You can set up as many category hierarchies as your organization
needs.

Related Articles

• Creating a Category Hierarchy [page 125]

• Building a Classification Rule [page 126]
• Modifying a Category Hierarchy [page 127]

8.4.4.1 Creating a Category Hierarchy

The system uses categories arranged in hierarchies as the basis for grouping transactions. A category
hierarchy can have the same name as a category within it. However, the names of category hierarchies must be
unique if the effective dates of the category hierarchies overlap.

Category hierarchies that share the same classifier type can share the same classifiers. However, hierarchies
that have different classifier types cannot share the same classifiers.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 125
Procedure

1. Choose Plan Data > Classification, and select the Classifiers tab.
2. ChoosePlan Data > Classification > Classifiers tab.
3. ChooseCreate.
4. In Category Type, select Category Hierarchy.
5. In Insert Data, provide the required details. If you are adding a category directly under the category
hierarchy, the system automatically fill in the Category Hierarchy name and leaves the Parent Category
field blank. When you add a subcategory below another category, the system automatically fill in both the
category hierarchy name and the parent category. You normally do not need to change the data in these
fields (an exception is moving a category). If your organization has created and implemented business
units, you can assign this classifier to a business unit by selecting from the Business Units dropdown. You
can only select business units to which you as a user have been assigned. If one or more business units
have been assigned to the parent category hierarchy or category, the category inherits those assignments.
You cannot assign business units that have not also been assigned to the parent category or category
hierarchy.
6. ChooseNext.
7. Review the updates and choose Submit.

 Note

You can save a category hierarchy without a classification rule, but the classification rule must be defined
before running the calculation.

The following tables provide examples of disallowed category hierarchy names and effective dates and
examples of allowed category hierarchy names and effective dates.

Disallowed Category Hierarchy Names

Category Hierarchy Name Classifier Type Effective Dates

Cat Hierarchy A Product January 2008 to EOT

Cat Hierarchy A Customer January 2008 to EOT

Allowed Category Hierarchy Names

Category Hierarchy Name Classifier Type Effective Dates

Cat Hierarchy A Product Jan 2008 to March 2008

Cat Hierarchy A Customer April 2008 to June 2008

Cat Hierarchy A Product July 2008 to Sept 2008

8.4.4.2 Building a Classification Rule

As you create a category hierarchy, you can build a classification rule for that category hierarchy using the
Classification Rule field. However, you can save category hierarchies without classification rules, then come

Incentive Management Admin Design Guide

126 PUBLIC Classification Data:Overview
back and define your classification rules later. Classification rules are required in the sense that they must exist
in order to match a given transaction to only one classifier in a given category hierarchy. If you have several
category hierarchies with the same classifier type, the same transaction can be classified under each category
hierarchy, but not twice under the same one.

 Note

The following instructions assume you have already created the Category Hierarchy. If you are creating a
category hierarchy and building the classification rule at the same time, skip to Step 3, else choose Plan >
Classifications , and select the Classifiers tab to proceed.

Procedure

1. Choose Plan Data > Classification.

2. Navigate and select the required Category Hierarchy name. If there is an existing rule, it displays in the
Classification Rule field in the detail pane.
3. Build the classification rule by doing one of the following:
• In the Classification Rule field, use wildcard matching and auto-matching to select the required legal
moves and operators.
• Choose the Formula field button to the right of the Classification Rule field to open the New Formula
dialog.
4. In the New Formula dialog, select from the legal moves pane to build the new rule. Choose Ok to save the
new rule.
5. Choose Save to save the Category Hierarchy.

8.4.4.3 Working with Classification Rules

A classification rule defines the condition that must occur in order for a transaction to be classified in the
associated category. Classification rules drive the classify stage of the calculation.

 Note

After you have created a category hierarchy with its required classifier type, you cannot change the
classifier type when you create the classification rule.

The classifier type used for the category determines what elements you can use to build the classification rule
for that category. For categories that use classifier types that are predefined for your organization, the classifier
fields have specific, descriptive names. You can also have custom attributes on the predefined classifier types,
which display on the vustom attributes of the associated workspace (for example, Customers could have a
custom attribute description that displays on the Custom tab in the Customers workspace). Each classification
rule defines in general terms how the field(s) on the transaction that is compared with the classifiers in the
category hierarchy. The comparison relationship can be:

• Equal to / not equal to

• Within a specified range (greater than, less than, and so forth)

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 127
• Like/Not like

The like and not like operators are used to comparing against a string that includes the "%" wildcard, which
means "match against any character in this position".

Valid Classification Rules

For a classification rule to be value, you must have, at a minimum, Transaction.xxx = Classifier.xxx.

In addition, you can also have the following in conjunction with the and operator (but it is not mandatory):

• Transaction.xxx = (a literal value)

• Classifier.xxx = (a literal value)

The following is prohibited:

• Transaction.xxx = Transaction.yyy
• Classifier.xxx = Classifier.yyy

Null Comparisons in Classification Rules

The system does not classify a transaction if the transaction’s field referred to in the classification rule is null.
For example, if you have the following transaction rule:Transaction.Billing.Industry <> ”r;Manufacturing”. If the
Transaction.Billing.Industry field has no value specified, the system does not classify the transaction. To avoid
transactions not getting classified, be sure to explicitly set the field comparison value in the classification rule.

Literals in Classification Rules

In addition to the comparison matching in a classification rule, you can include a portion of the classification
rule that compares a transaction field to a literal value. A classification rule must specify a comparison between
a classifier field and a transaction field. You cannot have a valid classification rule that consists solely of a
comparison to a literal value. An example of an invalid classification rule is "Transaction.Value greater than
$100.00." The system calculation ignores invalid classification rules.

 Note

For a literal comparison to a data field, it is recommended to put the literal value on the right side of the
expression.

Legal Moves for Building Classification Rules

When you are creating a classification rule for a category hierarchy, you choose the individual operations
and associated parameters from the Legal Moves that display in the New Formula dialog. A classification rule

Incentive Management Admin Design Guide

128 PUBLIC Classification Data:Overview
must specify a comparison between a classifier field and a transaction field. However, you can also build
classification rules that include comparisons between transaction fields and literal values. You cannot, however,
have a valid classification rule that consists solely of a comparison to a literal value. The calculation ignores
invalid classification rules.

 Note

When referring to one of the default classifier types in a formula or a classification rule, the ID displays in
legal moves like the following: Product.Product ID. For generic classifiers, the ID displays in legal moves like
the following:AreaCode.ID.

When creating classification rules that include literals using extended attributes, you should group the
extended attributes together. For example, instead of using the following classification rule:

(Product.Product ID = Transaction.Product ID And Transaction.Extended Attribute 1 = "A") Or

(Product.Product ID = Transaction.Product ID And Transaction.Extended Attribute 1 = "B")

you should group the generic attributes together as follows:

(Product.Product ID = Transaction.Product ID) And

(Transaction.Extended Attribute 1 = "A" Or

Transaction.Extended Attribute 1 = "B")

8.4.4.4 Category Hierarchy and Category Effective Dates

Category hierarchies and categories comply with the following effective date rules:

• A category’s effective date range must be less than or the same as the effective date range of the category
hierarchy. A category cannot be effective for a greater range of time than its category hierarchy.
• A category’s effective date range must be less than or the same as the effective date range of the category
that the subcategory belongs to. The subcategory cannot be effective for a greater range of time than its
owning category.

8.5 Working With Classifiers

A classifier is a unique identifier that a classification rule uses to match a field on a transaction during the
classification stage of the calculation.

When you create classifiers, they inherit the classifier type of the category hierarchy they associated with.
Hence, all the classifiers in a category hierarchy must be and are of the same classifier type. Classifiers are
attached to categories at the leaf-level in the category hierarchy. Each classifier represents a piece of business
information such as a Product Id number (PP478). Any sales transaction processed in the system that contains
a line with (PP478) is classified by the system so that the sales representative that sold that product will get
credit for the sale.

Classifiers, based on the business information that they want to use to compensate salespeople, can be
created first. Category hierarchies which support these classifiers can then be created later. However, you can

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 129
also create hierarchies and categories in a top-down manner, then create or import classifiers to attach to the
categories within these hierarchies.

There is no limit to the number of classifiers you can create (or import). You can add a classifier at the leaf level
of any category in any category branch within the category hierarchy. A classifier can exist in multiple category
hierarchies, but it can be attached only once in each hierarchy.

You can also create a classifier without associating it to a category hierarchy. However, you can associate a
category to the classifier later.

 Note

Unassigned Classifiers are classifiers that are assigned to a Classifier Type but are not associated to a
Category Hierarchy. Unassigned Classifiers are not considered for calculations and allocations and are not
associated to classification rules.

Related Articles

• Creating a Classifier [page 130]

• Deleting a Classifier [page 133]
• Assigning a Classifier to a Category [page 134]
• Versioning of a Classifier [page 137]

8.5.1 Creating a Classifier

You can create classifiers and then assign them to categories and subcategories within a category hierarchy
later, or you can create and assign classifiers in one single step.

You can also create Unassigned Classifiers, that is, create a classifier without associating it to a category and
then associate the classifier to a category hierarchy later on.

You can create as many classifiers as you need. When you create a classifier, you must assign an identifier.
The identifiers for the three predefined classifier types (Product ID, Customer ID, and Postal Code id) must be
unique. However, the identifiers for generic classifiers do not need to be unique.

Procedure

You can add a classifier to any category in the category hierarchy. A classifier can exist in multiple category
hierarchies but can exist in each one only once.

1. Choose Plan Data > Classification > Classifiers tab.

2. Do one of the following:
• To create an unassigned classifier (i.e, classifier with no associated category), select a classifier type,
and choose Create in the right panel.

Incentive Management Admin Design Guide

130 PUBLIC Classification Data:Overview
 All unassigned classifiers belong to a Classifier Type. They don’t belong to a specific Category or
Category Hierarchy.

• To create a classifier by associating a category, select a classifier type, navigate to the desired category
in the hierarchy view, and choose Create in the details panel.

3. Specify effective dates for the new object.

4. Enter an ID for the classifier. For example, if you are creating a product classifier from the Products
workspace, you might enter TC101 for the Product ID. The Summary panel immediately reflects with your
entry.
If your organization has created and implemented business units, you can assign this product to a business
unit by selecting from the businessunits dropdown. You can only select a business unit to which you as
a user have been assigned. If one or more business units have been assigned to the parent category, the
classifier inherits those assignments.
5. Enter values for the other fields as defined by your organization.
6. Optional. For information about assigning classifiers, see Assigning a Classifier to a Category [page 134].
7. Choose Save to save the classifier.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 131
  Note

You can download classifier data with associated category and classifier information using the Download
Excel Data option.

The following tables provide examples of disallowed category names and effective dates, and examples of
allowed category names and effective date.

Disallowed Classifier IDs

Classifier Type ID Name

Product Product ID = A A

Customer Customer ID = A A

Postal Code Postal Code ID = A A

Allowed Classifier IDs

Classifier Type ID Name

Product A
Product ID = A

Product B
Product ID = A

Customer C
Customer ID = A

Postal Code
Postal Code ID = C A, B, or anything else

Generic Classifier 1 ID = A A

Generic Classifier 2 ID = A A

Related Information

Working With Classifiers [page 129]

Incentive Management Admin Design Guide

132 PUBLIC Classification Data:Overview
8.5.2 Editing Multiple Classifiers (Bulk Edit)

You can update multiple classifiers in one go by using the Bulk Edit feature.

Procedure

1. Choose Plan Data > Classification > Classifiers tab.

2. First select the Classifier Type and then the respective Classifiers you wish to edit.
3. Choose Edit Selected in the the Ellipsis Menu (…).
4. Select the fields you want to edit and update as needed.

5. Choose Save. All selected classifiers will now display the updated field values.

Related Information

Working With Classifiers [page 129]

8.5.3 Deleting a Classifier

You can delete a classifier that was just created either manually or using import. You cannot delete a classifier if
it is referred to by a rule, a territory, or a lookup table.

When you delete a classifier, the warning “Are you sure you want to delete this Classifier and remove its
associated relationship with Categories” is displayed. If you click Yes, the classifier and its assignment to all
categories are deleted. Deleting a classifier removes all versions of the classifier from the the system.

However, the audit log in the Audit Log workspace retains information on the actions performed on the
classifier object, including its remove (delete) date, and information about the object itself.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 133
  Note

To delete a particular version of a category, use the Manage Versions option in the Ellipsis Menu (…).

8.5.4 Assigning a Classifier to a Category

You can assign a classifier to any category in the category hierarchy. A classifier can exist in multiple category
hierarchies but exist in each one only once. You can assign an existing classifier to a category or you select
a category and create and assign the classifier in a single step. A classifier can be assigned to additional
categories.

You can also move a classifier from one category to another by updating the parent category.

Assigning a Classifier in the Category Workspace

1. Choose Plan Data > Classifications > Categories tab.

2. Select the category to which you want to assign a classifier.
3. In the Category Details page, choose Create to add related data.
4. Use the Simple Search or Advanced Search option to find and select the classifiers. Search displays all
unassigned classifiers. You can select and assign several classifiers at the same time.

5. Choose Save. The selected classifiers are added to the category.

6. Optional. You can edit the related data using the Edit option. You can delete (remove) the assigned
classifiers using the Delete option.

Incentive Management Admin Design Guide

134 PUBLIC Classification Data:Overview
Assigning a Category to a Classifier in the Classifiers Workspace

1. Choose Plan Data > Classifications > Classifiers tab.

2. Navigate in the hierarchy view, and choose the classifier that you want to assign to a category.
3. In the Classifier Details page, choose Create to add related data.

4. In the Create Related Data popup, select the Category to which you want to assign the Classifier. Category
Hierarchy is automatically populated.
5. Choose Save.
6. Optional. You can edit the related data using the Edit option. You can delete (remove) the assigned
classifiers using the Delete option.

Moving a Classifier to a Different Category

1. Choose Plan Data > Classifications > Categories tab.

2. Select the category to which you want to move a classifier.
3. In the Category Details page, select the classifier you want to move.
4. Choose Edit to update related data.
5. In the Edit Related Data popup, select a new parent category from the Category dropdown.

6. Choose Save. The selected classifier is now moved to the specified category.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 135
Related Information

Working With Classifiers [page 129]

Working With Categories [page 120]
Classification Data:Overview [page 115]

8.5.4.1 About Classifier Assignments

Classifier assignment is the relationship created by assigning a classifier to a category for a specified period
of time. Classifier assignments are created when classifiers are added to categories. If the effective dates for
a category and classifier differ, the effective date of the relationship between the category and classifier is
determined by the overlap of effective dates.

You can perform bulk addition of classifiers to a category. This principle is illustrated in the following figures.

Classifier assignments can also be imported.

Related Information

Working With Classifiers [page 129]

Assigning a Classifier to a Category [page 134]

Incentive Management Admin Design Guide

136 PUBLIC Classification Data:Overview
8.5.5 Versioning of a Classifier

Effective dates of an associated classifier can be edited using the Manage version dialog. You cannot create
different versions of the association but will be able to edit the version dates. Hence, a version of the classifier
can be associated to a category. The same behavior applies to the classifier to category association.

You need to save the classifier or category before creating the association. If there are multiple versions of the
object, then the last version of the object in the assignment date range is displayed. .

8.5.6 About Classifier Types

The following predefined classifier types are predefined in the system:

• Products
• Customers
• Postal Codes

Your organization could add other user-defined classifier types. For example, if your company allocates credits
based on product information found on the transaction, you can use a category hierarchy with classifiers of
the Product classifier type to filter for transactions that contain specific product information. If your company
allocates credits based on both product and postal code, you can use two category hierarchies: one with
classifiers of the Product classifier type, and the other with classifiers of the Postal Code type. You could also
have more than one category hierarchy with the same classifier type.

For example, the administrator might create two category hierarchies with the Product classifier type, one for
regular company products and one for Special Product Incentives Fund (SPIF) containing products or groups
of products for which special commissions or bonuses are assigned for limited sets of dates. The system
supplies separate workspaces on the Classification tab for each of the predefined classifier types, as well as
separate workspaces for user-defined classifier types that your organization creates.

See Working With Classifiers [page 129] for more details.

Incentive Management Admin Design Guide

Classification Data:Overview PUBLIC 137
9 Credit Eligibility Rules Overview

The Credit Eligibility Rule workspace is used to create Credit Eligibility Rules which are used to generate
transaction pre-assignments by matching fields in the Transaction with the Territory mapping (specified
in Generic Classifier table). Territory mapping stored in the Generic Classifier table specifies what type of
transaction each Position (or Payee or Title) is eligible to get credit for. In the Credit Eligibility Rule, you
can specify which field in the Generic Classifier must be matched against which field in the Transaction.
Transaction pre-assignment record is created after the Credit Eligibility Rules are processed in the Territory
Processing stage. Transaction pre-assignment helps with filtering out candidate transactions that are eligible to
be credited.

Choose Plan Data > Credit Eligibility Rules to access the Credit Eligibility Rule workspace.

 Note

If the Credit Eligibility Rules workspace is not available on your tenant, create a support ticket to enable this
functionality.

Credit Eligibility Stage (CES) is a way of generating the transaction assignment from a Territory that is
defined in a relational structure. It is a pipeline stage which will directly create transaction assignment records
based on matching transactions for existing classification data. You can define Territory for a Position as a set
of entries in the Generic Classifier table.

For example, to define the same territory for a position selling laptop computers in the U.S. or desktop
computers in Canada, you will need to have the following entries:

After you run the CES stage (shown as Territory Processing in the pipeline run), it will match Sales Transaction
to the CES Territory (defined in Generic Classifier table as above) to generate records for the Transaction
Assignment table. With the generated Transaction Assignment, you can run the regular ECA (External Credit
Allocation) Credit Rule (i.e., Credit Rule with the Credit if they are identified on the Transaction option selected).

Multiple Credit Eligibility Rules can be used to generate Transaction pre-assignment for the same Territory
Mapping (i.e. the Generic Classifier record). Transactions can be assigned by the following standard methods:

• Positions only
• Payee IDs only
• Position and Payee ID combinations
• Titles

Incentive Management Admin Design Guide

138 PUBLIC Credit Eligibility Rules Overview
  Caution

When you have any active Credit Eligibility Rule, the pipeline will run the Territory Processing stage. The
Territory Processing stage will first delete all Transaction Assignment records for the period and then
run all active Credit Eligibility Rules to create the Transaction Assignments. If you have manually or
imported Transaction Assignment records that you want to preserve ( prevent from deletion by the pipeline
run), add the following entry in the CSTA_Preferences table:INSERT INTO CSTA_Preferences VALUES
('PreserveImportedTA', 'true'); Additionally, your Transaction Assignment records cannot have a
value in the GenericBoolean6 column.

Related Information

Configuring Credit Eligibility Rules [page 139]

9.1 Configuring Credit Eligibility Rules

The Credit Eligibility Rule workspace creates rules for transaction pre-assignments by matching fields in the
Transaction with the Territory mapping from the Generic Classifier table.

Best Practices

• The CES rule allows selecting only customer fields for matching. For other Classifiers, you can directly
populate the CSTA_Rule table.
• The CES rule supports direct matching. If you need to use relational operators (<, >, <=, >=, like), you can
change those in the CSTA_Rule table directly.
• CES makes use of the Generic Classifier table, so you must create a custom Generic Classifier Type to use
for CES Territory.
• It must be noted that CES runs for all the calendars.

Procedure

1. Define a new custom Generic Classifier Type in the Preferences > Customization workspace. This will be
used to store the CES Territory definition. Enable the Generic Attributes that will be used for the PayeeId/
Position/Title field and the matching Transaction fields plus other fields that you require.
Example: Create GenericClassifier type 'CES' and enable GenericAttribute1 for position. This field will be
used to specify the position. Enable GenericAttribute2 for productId. This field will be used to match the
SalesTransaction field.

Incentive Management Admin Design Guide

Credit Eligibility Rules Overview PUBLIC 139
2. Create a CES rule in the Plan Data > Credit Eligibility Rules workspace. The CES rule defines the mapping
rule for attributes in GenericClassifier (your CES Territory definition) to attributes in SalesTransaction or
Customer object. See Credit Rules Overview [page 142] for details.
Example: Select CES type, then add the matching condition Transaction.ProductID to match
GenericClassifier's productId. GenericClassifier's position field will be the matching position.
Perform the following steps:
1. Enter a Name for the CES Rule.
2. Select CES for Generic Classifier Type.
3. Add the Matching Condition:
• Select Product ID for Transaction Field.
• Select Generic classifiers for Matching Table.
• Select Product for Matching Table Field.
• Choose Add Match Condition to add additional Matching conditions.
• Select Country for Transaction Field.
• Select Billing for Address Type.
• Select Generic Classifiers for Matching Table.
• Select Country for Matching Table Field.
4. In Target field assignment, select Position for Generic Classifier Field Matching Position.
5. Choose Save Rule.

 Note

The Match Conditions section compares a field in a transaction with a field from a chosen table
(usually a Generic Classifier table). The matching rule conditions are treated as ANDs and not ORs
by the system. Each rule is matched once to determine if a given rule for a given transaction should
move on to the Successful Match Processing section. Match Processing is the exercise of stamping
the transaction with additional information that will help speed processing of candidate transactions.
The first part of the Successful Match Processing allows you to identify the type of transaction
pre-assignment stamp you are setting. (Transaction pre-assignment table refers to transactions and
people). The Stamp section allows you to select a field in the Generic Classifier table and stamp
(copy) that value into a field on the pre-assignment table so it can be referenced during Credit Rule
processing. The Matching Transaction Pre-assignment field is the resulting field that would be stamped
with the value. You can use the Add Post Process option to move more values to the transaction

Incentive Management Admin Design Guide

140 PUBLIC Credit Eligibility Rules Overview
 pre-assignment table and copy the information you want to pass to the pre-assignment tables for
processing in the pipeline.

3. Create the CES Territory in the Plan Data Classification workspace. This involves creating a
GenericClassifier for the CES Classifier Type in the GenericClassifier table. See Working With Classifiers
[page 129] for details.
For example: Create new Classifiers for CES Classifier Type to specify the CES Territory for the Position.
4. Create a Credit Rule in the Plan Data > Rules workspace and select the Credit if they are identified on the
Transaction option. This is also known as External Credit Allocation (ECA) based Credit Rule. See Creating
a Credit Rule [page 147] for details.
5. Run the pipeline. You can notice that the Territory Processing stage starts running. This stage will run the
CES rule and generate the Transaction Assignment.
The assignments generated for the matching SalesTransactions are displayed. You can see that the
attributes that match the GenericClassifier and the SalesTransaction based on the matching condition
for the CES are listed.

 Note

To import a CES Territory, you can also use the CLGC_Template to import the GenericClassifier via Express
Data Loader.

Related Information

Credit Eligibility Rules Overview [page 138]

Incentive Management Admin Design Guide

Credit Eligibility Rules Overview PUBLIC 141
10 Credit Rules Overview

A credit rule identifies the credits on which a plan operates and allocates them to position assignments.
The system uses credit rules to analyze transactions, orders, or rollable credits to determine which position
assignments should receive credits for a transaction. In addition to being created by credit rules, credits can
also be imported into the system and can be created manually.

As a best practice, it is recommended that you allow the system to calculate credits. Credit rules drive the
allocate credits and primary measurement step of the allocate stage of the calculation. The output of credit
rules, individual credits associated with position assignments, is used as input to primary measurement rules.
There are four kinds of credit rules: direct transaction credit, rolled transaction credit, direct order credit, and
rolled order credit rules.

The following table summarizes these credit rules, and identifies their inputs and their outputs.

Type of Credit Rules Description

Direct transaction Input is transactions; generates direct credits.

Rolled transaction Input is rollable credits that are based on transactions; gen-
erates rolled credits.

Direct order Input is orders; generates direct credits.

Rolled order Input is rollable credits that are based on orders; generates
rolled credits.

 Note

If a compensation plan relies on imported credits, you probably do not need to create credit rules for that
plan.

Related Articles

• Input and Filters in Credit Rules [page 143]

• Actions in Credit Rules [page 143]
• Creating a Credit Rule [page 147]

Incentive Management Admin Design Guide

142 PUBLIC Credit Rules Overview
10.1 Input and Filters in Credit Rules

In the Credit Rule editor, you can limit the data evaluated by a credit rule by specifying the input source, either
transactions or orders, and creating filters. The filters area for order credit rules is similar to the source and
filters area for a transaction credit rule, but you cannot specify a territory for an order credit rule.

 Note

The pre-assigned option, next to the Source field, is available only when the source is transactions and is
only used in conjunction with creating direct transaction credit rules.

In the filters area fields you can do the following:

• Condition—Enter a simple or complex expression of conditions that must be met for the rule to be
evaluated as true and fired.
• Territory—Select one or more territories, territory variables, categories, or classifiers on which to filter. You
can also build an expression that includes a combination of categories or classifiers or both with or without
territories or territory variable.
• Roll type—Specify the name of the roll type if the input is indirect (rolled) credits. The combination of
source and roll type affects how the rule is structured. If you select transaction as the source and leave
the roll type blank (thereby specifying that rolled credits are not used as input), you are creating a direct
transaction credit rule.

When a transaction or order meets the filtering criteria, it is evaluated against the condition in the rule.
Otherwise, the condition in the rule is not evaluated.

10.2 Actions in Credit Rules

When conditions specified in the filters area are met, the action or actions defined in this area are fired
(executed) and a credit output is produced. Among other things, you can specify in this area whether and
how the credit should or should not be held, whether duplicate credits are allowed, and whether the credit is
rollable.

Credit Rule Hold Types

In your credit rule action, you can specify that credits be held in particular situations. For example, you can
place credits that are above a certain amount on hold so they can be manually reviewed before they are
processed. Held credits are allocated according to their release date, rather than the compensation date of the
associated transaction. When a credit is held, the release date, if specified, sets the compensation date to be
the same. If the release date of a held credit is within the processing dates of a position assignment, the credit
is released. This happens even if the credit’s compensation date is outside the position assignment’s effective
dates.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 143
  Note

If a credit is held with an offset (some number of periods relative to the current period), the release date is
set to the last day of the offset period.

If the compensation date of a transaction is outside the position assignment’s credit dates but within the
processing date, credits are not generated. However, if an existing credit’s compensation date is within the
position assignment’s processing date, the credit is used in calculation processing. When you create a credit
rule, you choose one of the following for the hold type of the credits that rule creates.
Hold Types in Credit Rules:

Hold Type Description

Release Immediately Default setting. Credits are available immediately.

Indefinite Credits are held until manually released. Use this setting if
you need to review held credits before they are included in
compensation calculations.

An indefinite hold generates credits with a null release date

and compensation date set to End Of Time.

Period Type Choose the kind of period (such as month, quarter, or year)
and the offset. The offset is the number of periods relative
to the current period (in which the rule is run and the credit
is created) for which the credit should be held. For example,
if the offset is 2, the credit release date is set for 2 months
from the month the credit is created.

Note: If a credit is held with an offset, the release date is set

to the last day of the offset period.

If you set the offset to zero (0), the credit is available for the
current period. There is a subtle difference between ”release
immediately” and a period offset of zero:

• If the credit is released immediately, the credit’s com-

pensation date is the same as that of the associated
transaction.
• If the period offset is zero, the credit’s compensation
date is the same as the release date, which is the end of
the current period.

Specific Period Choose a specific named period, such as January 2008. The
release date is set as the last date of this period. The credit is
processed by any calculation run for this period.

Incentive Management Admin Design Guide

144 PUBLIC Credit Rules Overview
Duplicate Credits

When you create credit rules, you specify how the rule handles duplicate credits. A duplicate credit is defined
as one that has certain fields of the logical key that match an existing credit, and is based on the same source
as the existing credit.

 Note

For a transaction credit, the logical key includes the fields for the transaction, position, payee, credit type,
and IsHeld (Ever Held) field in Credits workspace), which can be either true or false/enabled or disabled.
For an order credit, the logical key includes the fields for sales order, position, payee, credit type, IsHeld
(Ever Held), and credit name (if the name is not null)

• Position/Payee
• Order, Txn
• Credit Type
• Credit Id
• Held Status

The following figure shows an example of the results of allowing or disallowing duplicate credits. Assume that
in your company, a manager receives rolled credit from two employees. For a particular transaction or order,
Employee A receives $500 direct credit and Employee B receives $600 direct credit for the same order. During
a calculation run, a rolled credit, Credit X, is created for the manager. Then when the second employee is
processed, Credit Y is evaluated to determine if it is a duplicate.

• If duplicate credits are allowed by the credit rule, then the total amount of $1100 rolls up to the manager.
Credit X is modified only if it rolls from the same source (Employee A). However, because it rolls from
another source (Employee B), the manager gets two credits.
• If duplicate credits are not allowed, then when Credit Y is evaluated and determined to be a duplicate, it is
not created. The manager receives either $500 or $600, depending on which employee is processed first.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 145
This example is for credits based on transactions. For credits based on orders, the processing of duplicate
credits is slightly different.

 Note

The rolled credit rule illustrated above is contained in the compensation plan for the manager position.

Duplicate Credits and Transaction Credit Rules

When creating a transaction credit rule (either direct or rolled), you can specify true or false in the Allow
Duplicates field in the Actions area.

• If you specify true, duplicate credits are allowed and credits are not evaluated to determine if they are
duplicates.
• If you specify false, the credit is evaluated to determine whether it is a duplicate. If it is a duplicate, the new
credit is not created nor is the original credit modified.

You can also enter any field with a Boolean value (true or false) or create an inline formulaic expression that
evaluates to a Boolean value. If the field or formulaic expression is false for the new credit, it is considered a
duplicate and is not created.

Duplicate Credits and Order Credit Rules

When creating an order credit rule (either direct or rolled), you specify how the rule handles duplicate credits
by selecting an option from the Allow Duplicates drop-down in the Actions area. The available options are as
follows:

• No Duplicates - Prevents duplicate credits from being created.

• Duplicates Allowed - Allows duplicate credits to be created. Does not differentiate if the credits are created
in different periods.
• Incremental Duplicates - Operates differently depending on whether or not the period of the duplicate is
the same as that of the existing credit.

If the periods are the same, the original credit is modified by the amount of the duplicate credit. If the periods
are different, The system creates an incremental order credit. An incremental order credit is an order credit
whose value is the difference between the current order credit value and the sum of previous, duplicate order
credits. An incremental order credit is generated from an order credit rule that specifies to create incremental
credits when duplicate credits occur.

 Note

Allowing incremental credits does not affect duplicate order credits that are in the same period.

The following example illustrates the possible results for duplicate order credits that are created in different
periods. Assume that your company has a special incentive for large orders that gives a 0.5% (.005) bonus. In
January a particular order is over $1 million, and a $5,000 credit is allocated. In February, the same order is
now over $1.5 million, and a $7,500 total credit is allocated. The following figure shows how different settings
for handling duplicate credits affect results.

Incentive Management Admin Design Guide

146 PUBLIC Credit Rules Overview
The three possible outcomes for this example are as follows:

• No duplicate credits allowed - The system does not add credits for the same order, and the initial $5,000
credit remains. The system generates an error message and do not generate the duplicate credit.
• Allow duplicate credits - The system creates a credit in February for $7,500, making two credits that total
$12,500. Since these credits are duplicates except for their periods, the additional credit is created.
• Generate an incremental order credit - The system adds the difference between the total credit and the
amount already credited and a credit for $2,500 is created in February.

10.3 Creating a Credit Rule

In addition to being created by credit rules, credits can also be imported into the system and can be created
manually.

Related Articles

• Creating a Rolled Order Credit Rule [page 147]

• Creating a Direct Order Credit Rule [page 149]
• Creating a Rolled Transaction Credit Rule [page 151]
• Creating a Direct Transaction Credit Rule [page 154]

10.3.1 Creating a Rolled Order Credit Rule

A rolled order credit rule generates a credit based on a rollable order credit.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 147
Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Create and select credit rule from the drop-down list. In the Rules Wizard workspace. The New
Credit Rule dialog opens.
3. Select a different calendar and specify new effective dates in the New Credit Rule dialog if required, and
then choose Ok. This displays the Credit Rule editor.
4. Enter a name for the rule in the Details panel. Rules are identified by their names in the Plan Wizard
workspace and in queries.
5. (Optional) Type rule's description.
If your organization has created and implemented business units, you can assign this credit rule to a
business unit by selecting from the Business Units drop-down. You can only select a business unit to which
you as a user have been assigned.
6. Select Order (Credit based on a rolled order credit) as the source for the rule. The Credit Rule editor
changes to reveal the fields for order credit rules.
7. (Optional) Specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

roll Type (Required) Specify what roll type(s) by which the incom-
ing credits are available. To specify multiple roll types,
select multiple, and from the Multiple dialog specify the
roll types, and choose OK.

Note: The roll Type option is what makes the rule a rolled
credit rule instead of a direct credit rule.

8. Specify the following in the Actions area:

Field Description

Output Name The system automatically creates the output name the
same as the rule name, but you can rename it. This is the
credit name.

Credit Type Select the type of credit that the rule generates. The pre-
defined credit types are Commission, Order, Quota, and
Revenue, but additional credit types can be created and
these pre-defined credit types can be deleted.

Incentive Management Admin Design Guide

148 PUBLIC Credit Rules Overview
 Field Description

Hold Type To hold the credit, specify what type of hold and when
to release the credit. The default is release immediately
(credits are not held and are available immediately), but
you can also select Indefinite, Period Type, and Specific
Period.

An indefinite hold generates credits with a null release

date and compensation date set to End Of Time. A hold
with an offset has a release date set to the end date of the
period.

Allow Duplicates (Optional) Select one of the following options: No

Duplicates, Duplicates Allowed, or Incremental duplicates.

Rollable (Optional) To make the created credits available to other

positions as rolled credits, select the Rollable check box.

Note: In most cases, rolled credits are not marked as rolla-

ble.

roll Date Enabled when the Rollable option is selected.

Amount Specify the value to be assigned to this credit (the default

is Transaction.Value).

You can directly enter a literal amount, point to an amount

stored in the system (value), or copy an amount from the
database (data field). You can also use an inline formulaic
expression or a named formula.

Max Amount (Optional) To establish a maximum allowable amount of

the credit, specify that maximum value here. If the credit
calculation yields an amount more than the specified max
amount, the system generates a credit with a value equal
to the max amount specified here. Once this maximum
amount is reached, the credit is no longer incremented.
This property is only available for indirect (rolled) credits.

9. (Optional) choose this node ( ) to reveal the fields if generic attributes are enabled. Populate the fields as
required for your installation.
10. Choose Add New Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
11. Choose Save to save the rule.

10.3.2 Creating a Direct Order Credit Rule

A direct order credit rule generates credit based on an order instead of a single transaction.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 149
Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Createand select Credit Rule from the drop-down list in the Rules Wizard workspace. This displays
the New Credit Rule dialog.
3. Select a different calendar and specify new effective dates in the New Credit Rule dialog and then choose
Ok. This displays the Credit Rule editor dialog.
4. Type a name for the rule in the detail pane. Rules are identified by their names in the Plan Wizard
workspace and in queries.
5. (Optional) Type rule description.
If your organization has created and implemented business units, you can assign this credit rule to a
business unit by selecting from the Business Units drop-down. You can only select a business unit to which
you as a user have been assigned.
6. Select Order(Credit based on the entire Order) as a source for the rule. The Credit Rule editor changes to
reveal the fields for order credit rules.
7. (Optional) Specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

For example, specify two formulas: one that calculates the

number of golf putters sold on an order, and a second
formula that calculates the number of golf drivers sold
on an order. Make the condition to the rule be that each
formula must result in greater than 1.

Roll Type Do not specify a roll type for a direct credit rule; you do so
for rolled credit rules.

8. In the Actions area, specify the following:

Field Description

Output Name The system automatically creates the output name the
same as the rule name, but you can rename it. This is the
credit name.

Credit Type Select the type of credit that the rule generates. The pre-
defined credit types are Commission, Order, Quota, and
Revenue, but additional credit types can be created and
these pre-defined credit types can be deleted.

Incentive Management Admin Design Guide

150 PUBLIC Credit Rules Overview
 Field Description

Hold Type To hold the credit, specify what type of hold and when
to release the credit. The default is Release Immediately
(credits are not held and are available immediately), but
you can also select Indefinite, Period Type, and Specific
Period.

An indefinite hold generates credits with a null release

date and compensation date set to End Of Time. A hold
with an offset has a release date set to the end date of the
period.

Allow Duplicates Select one of the following options: No Duplicates, Dupli-

cates Allowed, or Incremental duplicates.

Rollable (Optional) To make the created credits available to other

positions as rolled credits, enable the Rollable option.

Roll Date Enabled when the Rollable option is selected.

Amount Specify the value to be assigned to this credit (the default

is Transaction.Value).

You can directly enter a literal amount, point to an amount

stored in the system (value), or copy an amount from the
database (data field). You can also create an inline formu-
laic expression or a named formula.

9. (Optional) Choose the node ( ) to reveal the fields if generic attributes are enabled. Populate the fields as
required for your installation.
10. Choose Add New Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
11. Choose Save

10.3.3 Creating a Rolled Transaction Credit Rule

A rolled transaction credit rule generates a credit based on a transaction credit that rolls to the position
according to the specified roll type. Rolled transaction credits rules always use a transaction as their source.

 Note

Do not use sourceCredit.Relationship.Version() in a rolled credit rule. The direct credit that
generated the rolled credit passes the roll date, which determines the relationship version.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 151
Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Create and select Credit Rule from the new drop-down list in the Rules Wizard workspace. This
displays a New Credit Rule dialog.
3. Select a different calendar and specify new effective dates in the New Credit Rule dialog and then choose
Ok. This displays the Credit Rule editor.
4. Type a name for the rule In the detail pane. Rules are identified by their names in the Plan Wizard
workspace and in queries.
5. (Optional) Type rule description.
• If your organization has created and implemented business units, you can assign this credit rule to a
business unit by selecting from the business units drop-down. You can only select a business unit to
which you as a user have been assigned.
6. Accept the default Transaction as the Source for the credit rule.
For rolled transaction credit rules, do not enable the Pre-Assigned option.
7. (Optional) Specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

Territory Specify one or more categories, classifiers, territories, us-

ing automatic matching or the Formula field button. The
system evaluates only the transactions that match the
specified object or objects.

You can also specify a territory variable, and then custom-

ize the territory at different assignment levels.

Roll Type (Required) Specify the roll type(s) by which the incoming
credits are available. To specify multiple roll types, select
Multiple, and from the Multiple dialogs add and remove
roll types as needed, and choose OK.

Note: The Roll Type option is what makes the rule a rolled
credit rule instead of a direct credit rule.

8. Specify the following in the Actions area:

Field Description

Output Name
The system automatically creates the output name the
same as the rule name, but you can rename it. This is the
credit name.

Incentive Management Admin Design Guide

152 PUBLIC Credit Rules Overview
 Field Description

Credit Type Select the type of credit that the rule generates. The pre-
defined credit types are Commission, Order, Quota, and
Revenue, but additional credit types can be created and
these pre-defined credit types can be deleted.

Hold Type To hold the credit, select the type of hold and when to re-
lease the credit. The default is Release Immediately (cred-
its are not held and are available immediately), but you
can also select Indefinite, Period Type, and Specific Period.

An indefinite hold generates credits with a null release

date and compensation date set to End Of Time. A hold
with an offset has a release date set to the end date of the
period.

Allow Duplicates To indicate that duplicate credits can be created, specify

true. Otherwise, accept the default of False.

Allowing duplicates indicates that a position can receive

credits of the same credit type and hold status as the
original credit for the same transaction.

Note: If credits are from different transactions, they are

not considered duplicate credits and are therefore not af-
fected by this setting.

Rollable To make the created credits available as rolled credits to

other positions, select the Rollable check box.

Note: In most cases, rolled credits are not marked as rolla-

ble.

Amount Specify the value to be assigned to this credit (the default

is Transaction.Value).

You can directly enter a literal amount, point to an amount

stored in the system (value), or copy an amount from the
database (data field). You can also create an inline formu-
laic expression, or a named formula.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 153
 Field Description

Max Amount To establish a maximum allowable amount of the credit,

specify that maximum value here. If the credit calculation
yields an amount more than the specified max amount,
the system generates a credit with a value equal to the
max amount specified here. Once this maximum amount
is reached, the credit is no longer incremented. This prop-
erty is only available for indirect (rolled) credits.

If Allow Duplicates is set to true, this Max Amount applies

to the total of all duplicate credits. For example, if a credit
rule generates two duplicate credits of $100 each and the
Max Amount is set at $150, one of the credits is reduced
to $50.

9. (Optional) choose this node ( ) to reveal the fields if generic attributes are enabled. Populate the fields as
required for your installation.
10. Choose Add New Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
11. Choose Save.

10.3.4 Creating a Direct Transaction Credit Rule

A direct transaction credit rule generates a credit based on a transaction.

Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Click Create and select Credit Rule from the drop-down list in the Rules Wizard workspace. This displays the
New Credit Rule dialog.
3. Select a different calendar and specify new effective dates in the New Credit Rule dialog.
4. Click Ok. The Credit Rule editor opens.
5. Enter a name for the rule in the Details panel. The rule name(s) is the way rules are identified in the Plan
Wizard workspace and in queries.If your organization has created and implemented business units, you
can assign this credit rule to a business unit by selecting from the business units drop-down. You can only
select a business unit to which you as a user have been assigned.
6. (Optional) Type a text description of the rule.
7. Accept the default, Transaction(Credit based on an individual Transaction), as the source for the credit rule.
8. Enable the Pre-Assigned option(Credit if they are identified on the Transaction) if transactions are pre-
assigned to participants.
When the Pre-Assigned option is enabled, the system evaluates only those transactions that specify
position assignment information (in addition to any other filtering imposed by the rule). If the position
name, participant, and title fields on a transaction are all null the Pre-Assigned option is ignored. The
pre-assigned option can be combined with the option to filter by territory or category, which results in

Incentive Management Admin Design Guide

154 PUBLIC Credit Rules Overview
 the processing of just those pre-assigned transactions that match one the specified territory/category
information..
9. (Optional) Specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

Territory Specify one or more categories, classifiers, territories, us-

ing auto-matching or the Formula field button. The system
evaluates only the transactions that match the specified
object or objects.

You can also specify a territory variable, and then custom-

ize the territory at different assignment levels.

Rolling through Do not select a roll type for a direct credit rule.

10. Specify the following in the Actions area:

11. Field Description

Credit Name The system automatically creates the output name the
same as the rule name, but you can rename it. This is the
credit name.

Credit Type Select the type of credit that the rule generates. The pre-
defined credit types are Commission, Order, Quota, and
Revenue, but additional credit types can be created and
these pre-defined credit types can be deleted.

Hold Condition To hold the credit, specify what type of hold and when
to release the credit. The default is Release Immediately
(credits are not held and are available immediately), but
you can also select Indefinite, Period Type, and Specific
Period.

An indefinite hold generates credits with a null release

date and compensation date set to End Of Time. A hold
with an offset has a release date set to the end date of the
period.

Duplication Formula To indicate that duplicate credits can be created, specify

True. Otherwise, accept the default of False.

Allowing duplicates indicates that a position can receive

credits of the same credit type and hold the status that is
the same as the original credit for the same transaction.

Note: If credits are from different transactions, they are

not considered to be duplicate credits and are therefore
not affected by this setting.

Incentive Management Admin Design Guide

Credit Rules Overview PUBLIC 155
 Field Description

Rollup Credits? To make the created credits available to other positions as

rolled credits, enable the rollable option.

Amount Specify the value assigned to this credit (the default =

Transaction.Value).

You can directly enter a literal amount, point to an amount

stored in the system (value), or copy an amount from the
database (data field). You can also create an inline formu-
laic expression, or specify a named formula.

12. (Optional) Click this node ( ) to reveal the fields if generic attributes are enabled. Populate the fields as
required for your installation.
13. Click Add New Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
14. Click Save.

Incentive Management Admin Design Guide

156 PUBLIC Credit Rules Overview
11 About Measurement Rules

There are two kinds of measurement rules: primary measurement rules, and secondary measurement
rules. The primary measurement rules aggregate the credits or other items for position assignments.
Typically, aggregating credits involves summing the monetary value of credits. However, you can also
define measurement rules to aggregate credits in other ways, such as by different product lines and by
counting the number of units sold. Secondary measurement rules aggregate primary measurements or
perform calculations based on formulas, formulaic expressions, values, or data fields. You select primary
measurements and values from the list of legal moves when you create the secondary measurement rule.

To create a self-reference, you must save the rule first. A self-reference is when you refer to the output of the
rule in the rule itself.

Related Articles

• Creating Measurement Rules Overview [page 157]

• Creating a Primary Measurement Rule [page 158]
• Creating a Secondary Measurement [page 159]

11.1 Creating Measurement Rules Overview

When you create a measurement rule, you must define the input or source. If you choose credits, the rule
created is a primary measurement rule. If you choose other performance measures, the rule created is a
secondary measurement rule. You can limit which incoming credits are evaluated by a primary measurement
rule by filtering on territories, categories, or classifiers. For example, if you want a measurement rule to
evaluate only credits that are based on sales made through the distributor channel, you can create a condition
to establish that requirement—Territory: Distributor.

Finally, when you create a measurement rule, you define one or more actions of the rule. The selection of
available actions displayed depends on what you selected as input to this rule. You name the output of the
action; the output is an aggregate of the incoming credits and their values (primary measurement) or an
aggregate of other non-credit-based values (secondary measurement).

 Note

You can include both order and transaction credits in a measurement. However, if you do so, you cannot
use a filter on the transaction credit.

Incentive Management Admin Design Guide

About Measurement Rules PUBLIC 157
11.2 Creating a Primary Measurement Rule

The input to a primary measurement rule is credited. The output is a named measurement with the value of the
aggregate of the credit amounts that you specify.

Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Create and select the Measurement Rule from the New drop-down list in the Rules Wizard
workspace. The New Measurement Rule dialog opens.
3. Select a different calendar and specify new effective dates in the New Measurement Rule dialog.
4. Choose Ok. The Measurement Rule editor opens.
5. Enter a name for the primary measurement rule in the detail pane. Rule names display in the Plan Wizard
workspace and in queries.
6. (Optional) Enter a text description for the rule.If your organization has created and implemented business
units, you can assign this rule to one or more business units by selecting from the Business Units drop-
down. You can only select business units to which you as a user have been assigned. .
7. Select Credits(A Rule that Sums Up My Credits) as the source.

 Note

After you save the primary measurement rule, you cannot change the source.

8. (Optional) specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

Territory Specify either a category or a territory. The system only

evaluates the transactions that match the specified terri-
tories or categories.

You can also specify a territory variable, and then custom-

ize the territory at different assignment levels (position,
title, plan, and variable).

Note: To get the category, choose Formula, then type Cat

to bring up a list of all the categories.

9. In the Actions area, specify the following:

Incentive Management Admin Design Guide

158 PUBLIC About Measurement Rules
 Field Description

Output Name The system automatically creates the output name the
same as the rule name, but you can rename it.

Unit Type Specify the unit type of the created measurement.

Increment by The value, or the reference to the value, to associate with

this measurement. Each credit’s contribution value is the
increment amount.

You can enter an explicit amount (literal), use the result of

a formula, extract an amount stored in the system (peri-
odic named value), or copy an amount from the database
(data field).

10. Choose Add Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
11. Choose Save to save the rule.

11.3 Creating a Secondary Measurement Rule

A secondary measurement rule generates a secondary measurement, which can be an aggregate of primary
measurements or the result of a formula.

 Note

During the reward stage, the systemdoes not load a position assignment to calculate its secondary
measurement if there is no credit in the current period (even if there are values from prior periods).
The secondary measurement rule, in this case, is not looking to prior periods for dependent data. To
resolve this issue, you must create a secondary measurement rule on the same plan and include an
impossible condition (such as 1=2). This rule does not fire, but it does cause the position assignment to
be loaded. With the position assignment loaded, the prior period data upon which the original secondary
measurement rule depends is included.

Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Create and select Measurement Rule from the New drop-down list. The New Measurement Rule
dialog opens.
3. Select a different calendar and specify new effective dates in the New Measurement Rule dialog
4. Choose Ok. The New Measurement Rule editor opens.
5. Enter a name for the secondary measurement rule in the detail panel. The Rule names display in the Plan
workspace and in queries.

Incentive Management Admin Design Guide

About Measurement Rules PUBLIC 159
6. (Optional) Enter a text description of the rule.If your organization has created and implemented business
units, you can assign this rule to one or more business units by selecting from the Business Units drop-
down. You can only select business units to which you as a user have been assigned.
7. Select Other Performance Measures as the source (A Rule that Calculates other Key Performance
Measures). The Measurement Rule editor changes to reveal the fields for secondary measurement rules.

 Note

After you save the secondary measurement rule, you cannot change the source.

8. (Optional) Specify the following in the Filters are:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

9. specify the following in the actions are:

Field Description

Output Name The system automatically creates the output name the
same as the rule name, but you can rename it.

Unit Type Specify the unit type of the created measurement.

Increment by Specify the value, or the reference to the value, to asso-

ciate with this measurement.

You can enter an explicit amount (literal), use the result of

a formula, extract an amount stored in the system (peri-
odic named value), or copy an amount from the database
(data field).

10. (Optional) Choose the node to reveal the fields if generic attributes are enabled. Populate the fields as
required for your installation.
11. Choose Add New Output and specify information for the new action to add another action to the rule. If you
have multiple actions in a rule, the one rule generates multiple outputs.
12. Choose Save to save the rule.

Legal Move Editor

The Calculation Result function is introduced in the Condition and Measurement Amount legal move editor
windows of Secondary Measurement Rule.

Incentive Management Admin Design Guide

160 PUBLIC About Measurement Rules
12 Incentive Rules Overview

Incentive rules calculate the earnings of your sales force. They can be simple, using a single measurement as
input and producing a single output; or complex, using multiple inputs and producing multiple outputs. When
creating incentives rules, you need to ask the following questions:

• What information is required to calculate the incentive? For example, is the incentive compensation based
on a single measurement that represents a salesperson’s sales for a period of time, or is it based on the
individual credits allocated to that salesperson.
• What output information is required for reporting? For example, is a single amount representing the
compensation to be paid adequate, or do the individual outputs, known as commissions, to be reported
based on individual inputs.
• What are our incentives based on?
• If the incentive is to be calculated based on a rate, where does the rate come from? For example, is the rate
based on a flat rate of 10% or is it based on an incremental, stepped set of rates from a rate table.

The first two questions lead us to the fact that there two basic types of incentive rules: those that calculate
incentives only (basic incentive rules) and those calculate incentives and commissions (commission rules). To
answer the first question, you need to look at the source for the calculation. Following are several common
scenarios:

• The sales person was credited with 500 sales in a quarter, and those credited sales need only to be
aggregated (added up) into a single primary measurement. That single measurement can be used to
calculate the incentive. This improves performance but the detail needed for reporting is lost.
• The sales person was credited with 500 sales in a quarter, but instead of aggregating those credits into a
single measurement the commission on each sales needs to be calculated separately. The sum of these
measurements is then used to calculate the incentive. Performance is diminished, but the detail needed for
reporting is retained.

Having a reporting requirement is the most common reason to use commission level detail, but there are other
factors. Consider the following examples:

• Not every credit is to be used in the incentive value calculation. For example, of the sales person’s 500
credit sales, only 200 of them meet the additional requirement that the credit is used only if the sale
exceeded $500.
• Credit values do not directly correlate to the incentive value calculation. For example, the salesperson’s
incentive is based on 80% of the sales value, not 100%.
• Attributes other than the amount are used in the incentive value calculation. For example, the value to be
used in the incentive value calculation is stored in a generic attribute.

The various scenarios and examples discussed above are summarized in the following table. In addition to
the above scenarios, scenarios including input from secondary measurements, incentives, and a formula are
included. Incentives calculated based on a commission are commonly called bonuses.

Incentive Rule Inputs and Outputs

Result Type Input Source Output

Incentives Only 1 primary measurement 1 Incentive

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 161
Result Type Input Source Output

Incentives Only 5 secondary measurements 1 Incentive

Incentives Only 3 incentives 1 incentive

Incentives Only 500 credits from 1 primary measure- 1 incentive

ment

Incentives and Commissions 500 credits from 1 primary measure- 1 incentive and 500 commissions
ment

Incentives and Commissions 200 credits from 1 primary measure- 1 incentive and 200 commissions
ment, which has 500 credits

Incentives and Commissions A formula 1 incentive

When you create an incentive rule, the result type specified (Incentives Only or Incentives and Commissions)
determines whether the rule is a general incentive rule or one that includes commissions. A commission is
based on each credit that feeds into a measurement, and the incentive for that kind of rule is an aggregate
value of all the per-credit commissions.

 Note

To create a self-reference, you must save the rule first. (Self-references are references to the output of the
rule from within the rule; the reference is to the different period-based version of the rule’s output.

12.1 About Basic Incentive Rules

When you first navigate to the Incentive Rule editor, the editor defaults to the criteria for a basic incentive rule,
which is the input source of Measurement and result type of Incentives Only. The result type specified for the
rule (incentives only or commissions) determines whether it is a general incentive rule or one that includes
commissions.

Basic incentive rules are sometimes called aggregate credit commission rules, aggregate credit rules, or bulk
credit rules. The input to an incentive rule is a measurement or a formula; the output of an incentive rule is a
named incentive with a specific value and an associated period type. The output period type indicates when the
incentive is available for deposit (for example, the end of the current month or quarter).

Basic incentive rules require less processing time but do not provide the results detail of commissions
calculated for each credit. Basic incentive rules calculate incentives directly from the measurement, without
calculating intervening commission objects. When processing incentive rules during the Reward stage of the
calculation, The system compares performance measurements with targets and quotas for each position
assignment assigned to the plan.

Incentive Management Admin Design Guide

162 PUBLIC Incentive Rules Overview
12.2 Commission Rules

A commission rule is based on each credit that feeds into a measurement, and the incentive for that kind of
rule is an aggregate value of all the per-credit commissions. The result type of commission rules is Incentives
and Commissions. There is no Input Source. Commission rules (individual credits rules) calculate a value
for each credit of the measurement called a commission. Commission result objects can be viewed in the
Commission workspace. Commission objects are used by the rule to calculate incentives. You should use
commission rules in the following cases:

• Rates for each product are different.

• There is a special commission for single credits over a specified amount.
• The measurement is not based on the sum of credit values (for example, multiplies the credit values by
25%), but you want to base the commission amount on the actual credit value.

Credit Processing Order in Commission Rules

The commission rule processes the credits from the measurement in the following order:

1. Order by Compensation Date: Credits are processed based on their compensation date. Credits with an
earlier compensation date will be processed first.
2. Order by Credit Value: If multiple credits have the same compensation date, the credit with the lower value
will be processed first.

 Note

If a special order is required for processing credits, submit a support ticket, and customization will be
provided through a query override.

12.3 Result Type and Filters in Incentive Rules

When you create incentive rules, the result type specified (incentives only or incentives and commissions)
determines whether the rule is a general incentive rule or one that includes commissions. Unlike credit rules,
measurement rules, and deposit rules, you do not directly specify a “Source” for incentive rules in the Incentive
Rule editor. Instead, the input source for these rules is specified in the filters for commission rules and directly
in the actions for incentive rules. You can, however, limit the data evaluated by both incentive and commission
rules by specifying filter conditions.

The filters area for basic incentive rule is similar to the result type and filters area for a commission rule
(incentives and commissions input), but you can only specify a condition for a basic incentive rule. In the filters
area fields you can do the following:

• Measurement—the name of the attainment primary measurement on which this rule operates. The
measurement is the input to this rule. The list contains the primary measurements defined in the
measurement rules.
• Input Period Type—the measurement period that represents the set of credits for the calculation.
• Period Offset— a number used to offset the measurement period to a relative, prior period.

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 163
• Input From—indicates which measurement to use. The default setting is from current position, but you can
use a measurement from another position by selecting another position. If you select another position, you
must select a relationship.
• Relationship—if the Input From measurement is from another position, select the roll type for that
relationship.
• Condition—Enter a simple or complex expression of conditions that must be met for the rule to be
evaluated as true and fired.

12.4 Tiered Rate Tables

The input to basic incentive rules can be a rate table, a flat rate, or no rate, depending on your requirements.
Rate tables can be processed as either tiered or straight rate tables. To process a rate table as tiered based on
attainment, the following must be true:

• The value in the Quota field must have a currency unit type.
• The value in the measurement must have currency unit type.
• The rate table must be created with both input type and return type set to the percentage.

The following table illustrates this last point. If the input type and return type are not set correctly, the rate
table is not processed as a tiered rate table.

Rate Table Tiering

Input Return Type Tiered/Not Tiered

% % Tiered

% $ Not Tiered

$ % Not Tiered

To process a rate table as tiered based on source, the following must be true:

• The rate table input type must match the measurement unit type.
• The rate table return type must match the incentive unit type.

If the input type and return type are not set correctly, the rate table is not processed as a tiered rate table.

12.5 Straight Rate Tables

To process a rate table as straight not using Interpolate, the following must be true:

• The measurement and quota should have the same unit type.
• The rate table input type must be set to percentage.
• The rate table input type must match the Incentive unit type.

To process a rate table as straight using Interpolate, the following must be true:

Incentive Management Admin Design Guide

164 PUBLIC Incentive Rules Overview
• The measurement and quota should have the same unit type.
• The rate table input type must be set to percentage.
• The rate table input type must match the Incentive unit type.

12.6 Creating an Incentive Rule

The general incentive rule calculates an incentive based on a measurement or a formula. You can optionally
specify a flat rate to apply to the incentive amount. If you add an action to a basic or bonus incentive rule, you
can add an incentive or bonus action. There is no calculation difference between the two types of actions; the
difference is that the bonus action has quota and attainment fields used for reporting purposes. The output of
a general incentive rule is an incentive object.

Procedure

1. Navigate to Plan Data > Rules Wizard..

2. Choose Create and select Incentive Rule from the new drop-down list. This displays the New Incentive Rule
dialog.
3. Select a different calendar and specify new effective dates in the New Incentive Rule dialog,
4. Choose Ok. This displays the Incentive Rule editor.
5. Enter a name for the incentive rule in the Details panel. Rule names are the way rules are identified in the
Plan workspace and in queries.
6. (Optional) Enter a text description of the rule.
7. Accept the default, Incentives Only, as the Result Type for the rule.
8. (Optional) Add a Condition to the rule, by specifying a formulaic expression, a named formula, or a
comparison of data fields.
9. Create a general incentive rule action by specifying the following in the Actions area:

Field Description

Output Name The system automatically creates the output name the
same as the rule name, but you can rename it.

Output Period Type Select the period type of the created incentive.

Unit Type Select the unit type of the created incentive..

Input Source Select the source for the incentive. The choices are Meas-
urement or Other.

10. Specify the following if you select Measurement as the Input Source:

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 165
 Field Description

Measurement field In the field next to the Input Source drop-down, select the
name of the measurement that is to be used as input to
this rule.

Input Period Type Select the period type for the measurement. Be careful to
specify the correct period type for the measurement.

Period Offset To specify an offset, enter a positive number. You can use
offsets to specify a relative, prior period. Enter the num-
ber of periods to go back. For example, to use the April
monthly measurement in June, you specify 2 in the offsets
field.

Input From The default setting is the Current Position.

Note: The system uses only one measurement from one

of the subordinate positions, even in cases when there is
more than one subordinate position. There is no way to
determine which subordinate position’s object is supplied
to the rule. Because of this uncertainty, only use this rollup
feature when there is only one subordinate position speci-
fied in the roll relationship.

Input Multiplier Select an input multiplier.

If you specify a flat rate, specify the rate in the field to the
right of the Input Multiplier drop-down list box.

If you specify no rate, specify the amount of the incentive

in the field to the right of the Input Multiplier drop-down
list box.

If you specify the rate table, specify the name of the rate
table in the field to the right of the Input Multiplier drop-
down list box. Then, specify the quota and attainment
period.

Quota Specify a value to be compared to the measurement

to determine the attainment percentage (attainment =
measurement/quota).

You can specify a quota object, a fixed value, or a fixed

value variable

Attainment For commission rules that reference a rate table, specify

the attainment period.

For example, to compare year-to-date measurement (per-

formance) to the annual quota, specify ’r;year’ as the pe-
riod type.

11. Specify the following if your Input source is Other:

Incentive Management Admin Design Guide

166 PUBLIC Incentive Rules Overview
 Specify the input to the rule. This can be a formula,
Other input formulaic expression, or any legal move.

Amount field Enter a value or a formula in the field next to the Input
Source drop-down.

Input Multiplier For incentive rules that are not based on a measurement
input, you can choose between a flat rate or no rate.

If you specify a flat rate, specify the rate in the field to the
right of the Input Multiplier drop-down list box.

If you specify no rate, specify the amount of the incentive

in the field to the right of the Input Multiplier drop-down
list box.

12. To add another action to the rule, choose Add New Output and specify the above information for a
separate action. If you have multiple actions in a rule, the one rule generates multiple outputs.
13. Choose the node ( ) to reveal the fields if generic attributes are enabled. Populate the fields as required
for your installation.
14. Choose Save to save the rule.

Examples

Case 1:

Suppose that, Achievement Source (Measurement) = $220

Rate = Stepped Rate using Rate table having 2% (<=100% attainment) and 4% (>100% attainment)

Based on = Attainment

Sales Target = $12

Commission = Rate * Achievement Source = 2% * 12 USD = 0.24 USD

Commission = Rate * Achievement Source = 4% * 208 USD = 8.32 USD

Result = 0.24+8.32 = 8.56 USD

Case 2:

Achievement Source (Measurement) = $3300

Rate = Stepped Rate using Rate table having 2% (<=100% attainment) and 4% (>100% attainment)

Based on = Source

Amount (Apply Rate to Custom Formula) = $15

Commission = Rate * Custom Value = 2% * 15 USD = 0.3 USD

Commission = Rate * Custom Value = 4% * 3,285 USD = 131.4 USD

Result = 131.7 USD

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 167
Case 3:

Achievement Source (Measurement) = $220

Rate = Straight Rate using Rate table having 2% (<=100% attainment) and 4% (>100% attainment)

Based on = Attainment

Sales Target = $12

Attainment = Measurement / Quota = 220 USD / 12 USD = 1,833.33333333%

Result = 220*4% = 8.8 USD

Case 4:

Achievement Source (Measurement) = $12

Rate = Straight Rate using Rate table having 2% (<=100% attainment) and 4% (>100% attainment)

Set Interpolate checkbox true

Based on = Attainment

Sales Target = $12

Attainment = Measurement / Quota = 12 USD / 12 USD = 100%

Result = 0.02 USD (2%)

12.7 Creating a Commission Rule

Commission rules base the incentive amount on attainment performance (the measurement’s value compared
to the position assignment’s quota). Commission rules calculate the incentive amount by multiplying the
specified rate by the value of each credit in the specified measurement; the value of the incentive is the sum of
each per-credit commission. You can specify the rate to be based on a fixed value, a flat amount, the result of a
formula, or a rate table. When you specify a rate table, the rule functions as a step commission.

 Note

The output of a commission rule is commission objects and an incentive object; the incentive object is the
aggregate value of all commissions generated by the rule.

Procedure

1. Navigate to Plan Data > Rules Wizard..

2. Choose Create select Incentive Rule from the new drop-down list of the Rules Wizard workspace. This
displays New Incentive Rule dialog opens.
3. Select the different calendar and specify new effective dates in the New Incentive Rule dialog if required
4. Choose Ok. This displays the Incentive Rule editor.

Incentive Management Admin Design Guide

168 PUBLIC Incentive Rules Overview
5. Type a name for the commission rule in the Details panel. Rule names are the way rules are identified in the
Plan workspace and in queries.
6. (Optional) Type a text description for the rule. If your organization has created and implemented business
units, you can assign this rule to one or more business units by selecting from the Business Units drop-
down.

 Note

You can only select business units to which you as a user have been assigned. .

7. Select the Result Type of the rule. For the commission rule, select Incentives and Commissions. The
Incentive Rule editor changes to reveal the fields for commission rules.
8. Specify the following in the Filters area:

Field Description

Measurement Specify the name of the attainment primary measurement

on which this rule operates. The measurement is the input
to this rule. The list contains the primary measurements
defined in the measurement rules.

Input Period Type Select the measurement period that represents the set of
credits for the calculation.

Period Offset To specify an offset, enter a positive number. You can use
offsets to specify a relative, prior period. Enter the number
of periods back to go. For example, to use the April monthly
measurement in June, you specify 2 in the offsets field.

Input From To use the measurement from another position, specify the
input as Another Position. Otherwise, the default setting of
Current Position applies.

Note: If the system uses only one measurement from one of

the subordinate positions, even in cases when there is more
than one subordinate position, there is no way to determine
which subordinate position’s object is supplied to the rule.
Because of this uncertainty, use this rollup feature only when
there is a single subordinate position specified in the roll
relationship.

Condition (Optional) Specify a formulaic expression, a named formula,

or a comparison of data fields as a condition to the rule.

Specify the following In the Actions area:

Field Description

Output Name The system automatically creates this the same as the rule
name, but you can rename it.

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 169
Field Description

Output Period Type Specify the period type of the created commission. Select
the appropriate period type for which this incentive should
be generated and available for deposit.

Unit Type Select the unit type of the created commission. .

Input Multiplier Select either Rate Table, Flat Rate, or No Rate.

If you select Rate Table, specify the name of a rate table or

rate table variable.

If you select Flat Rate, specify a value to be used as a rate.

Specify the following if the rate is based on rate table:

Field Description

Input Amount Specify the amount of the created commission by either

specifying a data field, literal value, or other rule ele-
ment that calculates a currency value. By default, this is
Credit.Value. You can also choose to specify the measure-
ment contribution value or a field on the transaction.

Uses the amount that each credit contributed to the meas-

urement. For example, if the credit value is $100 and the
measurement uplifts the credits by 25%, the credit’s meas-
urement contribution value is $125.

Quota Specify a value to be compared to the measurement to de-

termine the attainment percentage (attainment = measure-
ment/quota).

In most cases, specify a fixed value or fixed value variable.

Attainment The attainment period is the period for which you are meas-
uring attainment.

For example, to compare year-to-date measurement (per-

formance) to the annual quota, specify ‘year’ as the period
type.

Incentive Management Admin Design Guide

170 PUBLIC Incentive Rules Overview
Specify the following if the rate is based on a flat rate:

Field Description

Input Amount Specify the amount of the created commission by either

specifying a data field, literal value, or other rule ele-
ment that calculates a currency value. By default, this is
Credit.Value. You can also choose to specify the measure-
ment contribution value or an attribute field on the transac-
tion.

Uses the amount that each credit contributed to the meas-

urement. For example, if the credit value is $100 and the
measurement uplifts the credits by 25%, the credit’s meas-
urement contribution value is $125.

Rate Specify the rate. This can be a literal value, a fixed value, a
fixed value variable, a formula, or any legal move.

If the rate is based on no rate, specify the following:

Field Description

Input Amount Specify the amount of the created commission by either

specifying a data field, literal value, or other rule ele-
ment that calculates a currency value. By default, this is
Credit.Value. You can also choose to specify the measure-
ment contribution value.

Uses the amount that each credit contributed to the meas-

urement. For example, if the credit value is $100 and the
measurement uplifts the credits by 25%, the credit’s meas-
urement contribution value is $125.

Quota Specify a quota.

 Note

Commission amounts for the period being run are calculated only for the set of credits specified by the
input period type.

To add another action to the rule, choose Add New Output and specify information for the new action. If you
have multiple actions in a rule, the one rule generates multiple outputs. Choose Save to save the rule.

Incentive Management Admin Design Guide

Incentive Rules Overview PUBLIC 171
13 Deposit Rules Overview

A deposit rule determines which incentives to pay and when. Incentives are available to be paid based on the
output period type of the incentive. For example, a quarterly bonus incentive is available for deposits in the last
month of each quarter (March, June, September, and December).

The system processes a deposit rule, and creates a deposit only if the incentive is available for deposit. For
example, a calculation run in February does not generate a deposit output for a quarterly incentive rule.

Related Articles

• Input and Filters in Deposit Rules [page 172]

• Deposit Rule Hold Types [page 173]
• Creating an Incentive based Deposit Rule [page 174]
• Creating an Incentive based Deposit Rule [page 174]

13.1 Input and Filters in Deposit Rules

In the Deposit Rule editor, you can limit the data evaluated by a deposit rule by specifying the input source,
either incentives or credits, and creating filters. In the filters area field for incentive-based deposit rules you can
do the following:

• Condition—Enter a simple or complex expression of conditions that must be met for the rule to be
evaluated as true and fired.

In the filters area field for detailed deposit rules you can do the following:

• Credit from Measurement—Enter a simple or complex expression of conditions that must be met for the
rule to be evaluated as true and fired.
• Input Period Type—Select the period type for the credit.
• Period Offset—To specify an offset, enter a positive number. You can use offsets to specify a relative, prior
period. Enter the number of periods to go back. For example, to use the April monthly measurement in
June, you specify 2 in the offsets field.
• Input From—The default Current Position. To use a credit from another position, specify the input as
Another Position.
• Relationship—If you specify that the input is from another position, you must also specify the roll
Relationship.
• Condition—Enter a simple or complex expression of conditions that must be met for the rule to be
evaluated as true and fired.

Incentive Management Admin Design Guide

172 PUBLIC Deposit Rules Overview
Actions in Deposit Rules

When the conditions specified in the filters area are met, the action or actions defined in this area are fired
(executed) and a deposit output is produced. Among other things, you can specify in this area whether and
how the deposit should or should not be held and what earning groups and earning codes should be used for
payment balancing.

13.2 Deposit Rule Hold Types

In your deposit rule action, you can specify that deposits be held in particular situations. New rules are added
to accommodate customer’s needs like hold condition on Deposits. For example, you can place deposits that
are above a certain amount on hold so they can be manually reviewed before they are processed. Held deposits
are allocated according to their release date, rather than the compensation date of the associated transaction.
When a deposit is held, the release date, if specified, sets the compensation date to be the same. If the release
date of a held deposit is within the effective dates of a position assignment, the deposit is released. This
happens even if the compensation date of the deposit is outside the position assignment’s effective dates.

If the compensation date of a transaction is outside the position assignment’s effective dates but within the
processing date, deposits are not generated. However, if an existing deposit’s compensation date is within
the position assignment’s processing date, the deposit is used in calculation processing. When you create a
deposit rule, one of the following hold types can be specified for the deposit.

Hold Types in Deposit Rules

Hold Type Description

Release Immediately Default setting. Deposits are available immediately.

Indefinite Deposits are held until manually released. Use this setting if
you need to review held deposits before they are included in
compensation calculations.

A deposit held indefinitely has a release date set to End of

Time.

Incentive Management Admin Design Guide

Deposit Rules Overview PUBLIC 173
Hold Type Description

Period Type Choose the kind of period (such as month, quarter, year or
decade) and the offset.

The offset is the number of periods relative to the current

period (in which the rule is run and the credit is created) for
which the deposit should be held. For example, if the offset
is 2, the deposit release date is set for 2 months from the
month the deposit is created.

Note: If a deposit is held with an offset, the release date is

set to the last day of the offset period.

If you set the offset to zero (0), the deposit is available

for the current period. There is a subtle difference be-
tween ”r;release immediately” and a period offset of zero:

• If the deposit is released immediately, the deposit’s

compensation date is the same as that of the associ-
ated transaction.
• If the period offset is zero, the deposit’s compensation
date is the same as the release date.

Specific Period Choose a specific named period, such as January, 2008. The
release date is set as the last date of this period. The deposit
is processed by any calculation run for this period.

Hold With Condition Use Legal Moves to set a condition to hold the deposit. The
deposit will be held indefinite if the condition is true. Set a
reason code (optional).

13.3 Creating an Incentive-Based Deposit Rule

You can create deposit rules that calculate regular deposits based on an incentive or a formula.

Procedure

1. Navigate to Calculations > Deposits.

2. Choose Create.
3. Select Position, Calendar, Name, Value, Earning Group and Earning Code.
4. Enter a name for the deposit rule. This name displays in the Plan workspace and in queries.
5. Optional: Enter a text description of the rule.
6. If your organization has created and implemented business units, you can assign this rule to one or more
business units by selecting from the Business Units dropdown. You can only select business units that are
assigned to you.

Incentive Management Admin Design Guide

174 PUBLIC Deposit Rules Overview
7. Accept the default, Incentives, as the Source for the deposit rule.
8. Optional: Specify the following in the Filters area:

Field Description

Condition Specify a formulaic expression, a named formula, or a

comparison of data fields as a condition to the rule.

9. Specify the following in the Actions area:

Field Description

Output Name The sytsem automatically creates the output name the
same as the rule name, but you can rename it.

Deposit names are shown in searches and payment and

balance information.

Unit Type Specify the unit type of the created deposit. The options
are Currency, Percent, Quantity, or Integer.

Deposit Value Specify the incentive or formula. To specify more than one
incentive, use a formulaic expression or formula. When
you specify an incentive, the Incentive Input Reference
Editor dialog opens.

Earning Code Earning code differentiates deposits within an earning

group. These codes help external accounting systems
track departmental earnings. Earning codes can be en-
tered using the following methods:

• Type a text string into the field using double quota-

tions. For example, enter ‘SPIF’ to dynamically create
an earning code for SPIF (Sales Promotion Incentive
Fund). Earning codes entered through this method
will not be available for other deposit rules.
• Select an earning code from the dropdown in the
Earning Code workspace. Earning groups added in
the Earning Group workspace are available for all de-
posit rules.
• Select Formula Field to create an earning code for-
mula.

Earning Group Groups similar types of deposits. Positive and negative

balances within an earning group are offset against each
other. Earning Groups can be entered using the same
methods as Earning Codes.

Release Date The release date drivers when this deposit will be released
and processed into further parts of the compensation cal-
culation

Incentive Management Admin Design Guide

Deposit Rules Overview PUBLIC 175
 Field Description

Reason Code Identifier created by a user to identify why an action was

taken, for example, to identify why a manual credit was
created

Ever Held Select a hold type.

10. (Optional) Choose the node ( ) to view the related fields if generic attributes are enabled. Populate the
fields as required for your installation. To add another action to the rule, choose Add New Output and
specify information for the new action. If you have multiple actions in a rule, the rule generates multiple
outputs.
11. Choose Save to save the rule.

13.4 Creating a Detail Deposit Rule

A detail deposit rule generates a deposit based on credit. For a detail deposit rule, you must specify primary
measurement as a filter for which the credits are deposited. You can also specify a condition as an additional
filter mechanism.

To generate individual deposits based on orders or some other attribute, you must specify a unique
earning code or earning group. For example, to generate deposits based on orders, you must specify
Credit.Order.OrderID as the earning code. To generate deposits based on a custom attribute, such as Customer
ID, you must specify that attribute as the earning code.

Procedure

1. Navigate to Plan Data > Rules Wizard.

2. Choose Create and select Deposit Rule from the New dropdown. The New Deposit Rule dialog opens.
3. Select a different calendar and specify new effective dates in the New Deposit Rule dialog if required, and
then choose OK. The Deposit Rule editor opens.
4. Enter a name for the detail deposit rule in the Details panel. This name displays in the Plan Wizard
workspace and in queries.
5. Optional: Enter a text description of the rule. If your organization has created and implemented business
units, you can assign this rule to one or more business units by selecting from the Business Units
dropdown. You can only select business units for which you have been assigned as a user.
6. Select Credits as the source. The Deposit Rule editor updates to display the related fields for detail deposit
rules.
7. Specify the following in the Filters area:

Incentive Management Admin Design Guide

176 PUBLIC Deposit Rules Overview
 Field Description

Credits from Measurement Specify a primary measurement by which the system de-
termines which credits to deposit.

Input Period Type Select the period type for the credit.

Be careful to specify the correct period type for the credit.

Period Offset To specify an offset, enter a positive number. You can use
offsets to specify a relative, prior period. Enter the num-
ber of periods to go back. For example, to use the April
monthly measurement in June, you specify 2 in the offsets
field.

Input From The default setting is Current Position.

To use a credit from another position, specify the input

as Another Position. If you specify that the credit comes
from another position, you must also specify the roll Rela-
tionship.

Condition (Optional) Specify a formulaic expression, a named for-

mula, or a comparison of data fields as a condition to the
rule.

8. Specify the following in the Actions area:

Field Description

Output Name The system automatically creates the output name, and it
is the same as the rule name. You can rename the output
name if required.

Deposit names are displayed in Search, Payment, and bal-

ance information.

Unit Type Specify the unit type of the created deposit. The options
are Currency, Percent, Quantity, or Integer.

Deposit Value Specify the credit information (for example, Credit.Value).

You can type in the value or use the Formula editor to
select the values.

Incentive Management Admin Design Guide

Deposit Rules Overview PUBLIC 177
 Field Description

Earning Code Earning code differentiates deposits within an earning

group. These codes help external accounting systems
track departmental earnings. Earning codes can be en-
tered using the following methods:

• Type a text string into the field using double quota-

tions. For example, enter ‘SPIF’ to dynamically create
an earning code for SPIF (Sales Promotion Incentive
Fund). Earning codes entered through this method
will not be available for other deposit rules..
• Select an earning code from the dropdown in the
Earning Code workspace. Earning groups added in
the Earning Group workspace are available for all de-
posit rules.
• Select Formula Field to create an earning code for-
mula.

Earning Group Groups similar types of deposits. Positive and negative

balances within an earning group are offset against each
other. Earning groups can be entered using the same
methods as Earning Codes.

Hold Type Select a hold type.

9. Choose the node ( ) to view the related fields if generic attributes are enabled. Populate the fields as
required for your installation.
10. To add another action to the rule, choose Add New Output and specify the required information for the new
action. If you have multiple actions in a rule, the rule generates multiple outputs.
11. Choose Save to save the rule.

Incentive Management Admin Design Guide

178 PUBLIC Deposit Rules Overview
14 Formulas

A formula rule element is a reusable mathematical expression that can be used in compensation rules, a rate
tables, or lookup tables. You can also nest formulas within other formulas.

Formulas are limited to the context in which they are created as indicated by the rule type icon. For example,
you cannot create a formula as a condition in an incentive rule then use that same formula in a measurement
rule.

You can create a formula either directly in the Formulas workspace, or by clicking the Formula button to open
the Formula editor.

 Note

Large expressions or formulas must be split into multiple formulas, for performance and readability
reasons. For example, if you have a formula that uses over 20 operators, it is easier to read and is processed
faster if you split it into two formulas.

Related Articles

• Formulas Workspace [page 179]

• New Formula Dialog [page 181]
• Legal Moves [page 182]
• Using Legal Moves [page 184]
• Referencing Measurements and Incentives [page 188]
• Creating a Formula [page 194]
• Editing a Formula [page 195]
• Deleting a Formula [page 195]
• Finding Objects Related to Formulas [page 196]

14.1 Formulas Workspace

Navigate to Compensation Elements > Formulas to access the Formulas workspace.

The Formula workspace contains two different panels:

• Formula Summary
• Formula Details (General Information and Associations)

Incentive Management Admin Design Guide

Formulas PUBLIC 179
Formula Summary

You can create new formulas, edit existing formulas, and delete formulas from the options available in the
toolbar.

General Information Tab

The General Information tab contains the following areas:

• Return Type field—Specifies the unit type of the formula result.

• Expression pane—Shows the entire formula and all parameters.
• Function pane —Shows a brief description of the selected function and its parameters. To display the
detail, click one of the parameters in the Formula pane.
• Rule Usage
• Legal Moves editor —Select from the list of legal moves to populate the input and parameters to your
formulas or expressions.

Legal Move Editor is organized into a column for:

• Literals
• Functions

Incentive Management Admin Design Guide

180 PUBLIC Formulas
• Data Fields
• References

The Legal Move Editor box has Clear All and Reset buttons available. This reduces time and effort for the
Administrator to edit an existing expression.

The Clear All and Reset options are available in the following workspaces:

• Formulas
• Rules Wizard
• Plans Wizard
• Classification
• Territory

Clear All clears out the current expression. Reset reverts to the last saved expression.

Associations Tab

From the Associations tab, you can view the rules that use the formula and the elements associated with the
formula.

14.2 Formula Editor

You use the formula editor in two ways:

• To create formulas and save them with a name

• Or, to create formulaic expressions.

A formulaic expression is used only by the current rule object. A saved formula, like a rule created in the
Formulas workspace, can be reused by other rule objects (rules or rule elements).

Incentive Management Admin Design Guide

Formulas PUBLIC 181
Related Information

Legal Moves Overview [page 182]

14.3 Legal Moves Overview

When constructing formulas or formulaic expressions, you must specify parameters (literals, functions, data
fields, and references) and operators. The items you can select are determined by the context that you are
working in. The selections allowed representing the next “legal move” that you can make.

Legal moves are displayed in the legal moves pane in the Formulasworkspace when creating a new formula,
Advanced Search dialog, and Search for Related Object dialog. When building expressions directly in a
workspace, for example when building classification rules, the logic of the next “legal move” is also applied.

• Return Type—Determines content of the Legal Moves pane.

• Expression (Formula edit ) pane—Shows the entire formula and all parameters.
• Legal Moves pane—Displays the legal move items that are available. Legal move items are organized into
the following types:
• Literals—Items such as true, false, units of time, and so on.
• Functions—Predefined, reusable operations that can be used in compensation rules.
• Data fields—Fields associated with objects, such as the participant's base salary.
• References—Point to data items such as variables, rule elements, measurements, or incentives.

Incentive Management Admin Design Guide

182 PUBLIC Formulas
Related Articles

• Available Legal Moves [page 183]

• Formatting of Items in the Expression (Formula) Edit Pane [page 183]

14.3.1 Available Legal Moves

Contents of the legal moves pane are influenced by the following factors:

• The context that the formula is being created within in the Formula editor. For example, if you are using
the Formula editor to create a condition for a credit rule, the data fields available would differ from those
available for the condition of a deposit rule.
• The return type of the formula. For example, the Legal Moves available to create a formula with a return
type of Boolean would differ from those available to create a formula with a return type of date.
• Whether specific attributes have been enabled. For example, you must enable generic attributes for
Transaction Payee Pre-Assignments so that the Transaction Extended and Transaction Generic attributes
are included in the list of data fields.

14.3.2 Formatting Items in the Expression (Formula) Edit

Pane

When Legal Moves items are specified, the following formatting rules are applied in the Expression (Formula)
Edit Pane:

• Upon selecting a reference, the reference type name goes away and all that is left is the name of the
selected object. This makes items such as formulas easily readable at a glance.
• Variables and Result References (for example, measurements and incentives) are italicized to indicate data
coming from another object.
• Variables and references to fixed values, territories, and rate tables are in green text to indicate data
coming from rule elements.
• Data fields are in plain, black text.
• Literals are in blue text, including data types (such as month, year, commission, bonus, and so forth).
• Period types associated with an object (such as a period type of an incentive) are displayed in the format
ofObjectName:PeriodType. For example, BookedRevIncentive:quarter.
• If offset amounts are specified for measurement and incentive references, they are displayed in the format
Object Name:Period Type-Offset Amount. For example, BookedRevIncentive:quarter-3, where 3 is the
offset amount.
• If you reference a data type, such as a reason code, you can reference it by the ID, such as
Transaction.Reason Code.ID.

Incentive Management Admin Design Guide

Formulas PUBLIC 183
14.4 Using Legal Moves Overview

The following procedure provides an overview of how to use legal moves.

Procedure

1. Specify the return type. This is the unit type of the formula result.
2. Specify the literals, functions, data fields, or references and operators required to build the formula in the
Formula edit panel. If you have chosen a function, the function's parameter details display in the Function
Detail pane.
3. Select a parameter in the Formula Definition pane for each parameter, and then select an item from the list
of available legal moves.
4. To display a list of available literals, functions, data fields, and references and operators, you can type an
asterisk (*) in the Formula Edit pane to use wildcard matching. Or, you can use auto-matching and type the
first few letters of the literal, function, data field, or reference name. You can also double-click the name
of the object to select it. An item that is shaded in blue indicates that the expression is either incomplete
or incorrect. Although you can save an incomplete or incorrect formula, you must correct the error before
you can use the formula. You can copy and paste legal move expressions within and across workspaces. In
some cases, such as when copying a formula from within a rate table, you must first open the New Formula
dialog before you can copy the expression. If you must copy text in the process of creating and modifying
objects, use an ASCII text editor such as Notepad.

Related Articles

• Specifying Strings [page 184]

• Specifying Listed and Unlisted Data Fields [page 185]
• Specifying Operators [page 187]
• How Input to Formulas Determines Range of Use [page 188]

14.4.1 Specifying Strings

You can include strings as parameters in your formulas. To enter a string literal, enclose it in double quotation
marks, such as: “Golf Rep”.

For example, to compare the above string to a field you might construct an expression such as the following in
the Formula Edit Pane: Credit.Comments = “Golf Rep”

Incentive Management Admin Design Guide

184 PUBLIC Formulas
Related Information

Using Legal Moves Overview [page 184]

14.4.2 Specifying Listed and Unlisted Data Fields

You can include available data fields in your (formulas) Expression.

For example, to construct a Boolean formula comparing the Credit Release Date to the Credit.Roll Date
(Credit.Release Date = Credit.Roll Date) you would first specify Credit.Release Date as shown in the following
figure.

However, some data fields are not specifically listed in the Legal Moves pane, but the items that contain them
are listed. For example, to use the company name from the transaction billing address, you must first specify
“Transaction.Billing? in the Formula Edit pane. If you then type a period “.? after “Billing?, you can access the
transaction billing address fields, such as “Transaction.Billing.Company? as shown in the following figure.

Incentive Management Admin Design Guide

Formulas PUBLIC 185
14.4.3 Specifying References

You can include available references in your formulas.

References are ways to point to a data object, such as the items listed in the following table. Items that you can
reference from Legal Moves

References Items

Category* Lookup Table Variable

Category Hierarchy* Measurement

Classifier* Period

Credit Type* Period Type*

Event Type* Quota

Fixed Value Rate Tables*

Fixed Value Variable Roll Type

Formula Territory*

Incentive Unit Type*

Lookup Table

*These objects can only be referenced as function parame-

ters.

Incentive Management Admin Design Guide

186 PUBLIC Formulas
When you specify a reference in a formula, the system follows it with a colon (:). You must specify the exact
reference item. For most references, you can select an item using wildcard matching or automatic matching
and in many cases, you can actually use the Create New Object option to create an inline object as shown in the
following figure. There are some exceptions when working with references:

• There is no Create New Object option for quota objects, so you cannot create quotas inline.
• When you specify an Incentive or Measurement, the Incentive Input Reference and Measurement Input
Reference dialogs are displayed.

The display format, type color, and style, of the references, are as follows:

• Rule element (fixed values, lookup tables, formulas, quotas, rate tables, and territories) references are
displayed in green text to indicate that the data is coming from rule elements. Categories are also
displayed in green text. Variables and formulas display in green text in lookup table cells (when the cell
is selected).
• Result data (measurements and incentives) references are displayed in black italicized text to indicate data
coming from another object. The period types associated with these references are displayed in the format
ofobjectName:periodType (for example, BookedRevIncentive: quarter).
• Rule element variable (fixed value variables, rate table variables, and territory variables) references are
displayed in green and italicized text.
• Period type (month, year, and so on), event type, roll type, and credit type references are displayed in blue
text to indicate that the data is from administration data or a data type.
• Classifiers to references are also displayed in blue text.

14.4.4 Specifying Operators

You can specify operators by typing them in or using wildcard matching as shown in the following figure. Only
those operators that are valid in the current context are displayed.

The list of available operators could include one or more of the following:

• * (multiplication)
• + (addition)
• <> (not equal to)
• - (subtraction)

Incentive Management Admin Design Guide

Formulas PUBLIC 187
• <= (less than or equal to)
• = (equal to)
• / (division)
• >= (greater than or equal to)

14.4.5 How Input to Formulas Determines Range of Use

The data used in a formula determines the type of compensation rule in which you can use the formula. Just
as different types of data are available during different stages of calculation processing, formulas use different
types of data for different types of rules.

For example, if you use transaction data in a formula, then the formula can be used only in direct credit rules.
If you do not use calculation-dependent data in a formula, then you can use the formula in any type of rule and
also in a rate table. For example, a formula that multiplies a fixed value by another fixed value can be used in
any type of rule and also in a rate table. All formulas must return a value. Rate tables can use formulas that
use fixed values as input or can be used in an incentive rule (input of measurements, or credits for per-credit
commissions).

Related Information

Using Legal Moves Overview [page 184]

14.5 Referencing Measurements and Incentives

You can reference the output of a measurement or incentive rule from another rule, formula, or rule element.

 Note

When making changes to references to measurements or incentives, the changes affect all versions of the
referencing rule or formula.

Related Articles

• Referencing Incentives [page 189]

• Referencing Measurements [page 191]

Incentive Management Admin Design Guide

188 PUBLIC Formulas
14.5.1 Referencing an Incentive

You can include in your rules, formulas, or expressions a reference to an incentive. An incentive reference
includes an incentive rule’s output value of the specified period type in your calculation. Some rules, such as
bulk commission rules, have the mechanism to refer to an incentive built into the rule. Other rules, such as
deposit rules, require that you specify the incentive reference by way of the Incentive Reference Editor dialog.

 Note

A self-reference is a reference to a different period type of the rule’s output. For example, within a quarterly
incentive rule, you can refer to the year-based version of that incentive. Self-references can occur in
measurement or incentive rules.

Procedure

1. Navigate to Compensation Elements > Formulas .

2. Choose the Incentive Input item in the list of references in the Legal Moves panel. The system opens the
Incentive Input Reference dialog.
3. Specify the following information for the incentive:

Field Description

Calendar
Specify the calendar appropriate within the context from
which you are creating the reference.

For example, if you are creating an incentive reference

from a deposit rule, ensure that the two rules are based on
the same calendar.

Incentive Specify the name of the incentive on which this rule or for-
mula operates using auto-matching, wildcard matching,
or the Search field button. The incentive is the input to this
rule. The list contains the incentives defined in the bonus,
per-credit commission, and commission rules.

Input Period Type

Select the incentive period that represents the appropri-
ate incentive value for the calculation.

Be careful to specify the correct period type for the incen-

tive.

Incentive Management Admin Design Guide

Formulas PUBLIC 189
 Field Description

Offset To specify an offset, enter a positive number. You can use

offsets to specify a relative, prior period. Enter the num-
ber of periods to go back. For example, to use the April
monthly measurement in June, you specify 2 in the offsets
field.

Position source
The default setting is Direct’

To use the incentive from another position, specify the

input as Indirect. If you specify that the incentive comes
from another position, you must also specify an operation
for the List Operation and the Relationship.

List Operation
If you have specified that the incentive input comes from
another position, you must also specify how to handle
multiple inputs (if there are any):

• Sum of All Inputs

• Average of All Inputs
• Error if more than one input

Note: If the reference to the incentive is from within the

Sum Prior Measurements function, the list operation op-
tion is not available.

Relationship Specifies the relationship for the measurement.

4. Choose OK to use the specified incentive input. The system displays the name and period type of the
specified incentive input.

Sum Related Incentives

Select the Sum of All Inputs as a list operation in an incentive or deposit rule to add up a group of related
incentives. The related incentives are those that have the same name and are from subordinates one roll
relationship away (with the specified roll type).

Incentive Management Admin Design Guide

190 PUBLIC Formulas
14.5.2 Referencing a Measurement

You can include in your rules, formulas, or expressions a reference to a measurement. A measurement
reference includes a measurement rule’s output value of the specified period type in your calculation.

Procedure

1. Navigate to Compensation Elements > Formulas .

2. Choose the Measurement reference from the References list in the Legal Moves panel. The system opens
the Measurement Input Reference dialog.
3. Specify the following information for the measurement and choose OK to use the specified measurement
input.

Incentive Management Admin Design Guide

Formulas PUBLIC 191
Field Description

Calendar
Specify the calendar appropriate within the context from
which you are creating the reference.

For example, if you are creating a measurement reference

from an incentive rule, ensure that the two rules are based
on the same calendar.

Measurement Specify the name of the attainment measurement on

which this rule operates using wildcard matching, automatic
matching, or the Search field button. The measurement is
the input to this rule. The list contains the measurements
defined in the measurement rules.

Input Period Type

Select the period type for the measurement.

Be careful to specify the correct period type for the meas-

urement.

Period Offset To specify an offset, enter a positive number. You can use
offsets to specify a relative, prior period. Enter the number
of periods to go back. For example, to use the April monthly
measurement in June, you specify 2 in the offsets field.

List Operation
The default setting is Current Position.

To use the measurement from another position, specify the

input as Another Position. If you specify that the measure-
ment comes from another position, you must also specify an
operation for the List Operation and the Relationship.

If you have specified that the measurement input comes

from another position, you must also specify how to handle
multiple inputs (if there are any):

• Sum of All Inputs

• Average of All Inputs
• Error if more than one input

Note: If the reference to the incentive is from within the

Sum Prior Incentives function, the list operation option is not
available. The list operation option is also not available if you

Relationship Specifies the relationship for the measurement.

Incentive Management Admin Design Guide

192 PUBLIC Formulas
Sum Related Measurements

Select the Sum of All Inputs as a list operation in a secondary measurement, incentive, or deposit rule to add
up a group of related primary or secondary measurements. Measurements are related if they have the same
name; they can be summed only from subordinates one Roll relationship away (with the specified Roll type).
The following figure illustrates an example of how you could aggregate measurements up a Rollup hierarchy,
rather than Rolled credits.

For example, you can Roll measurement data up a Roll hierarchy by summing related measurements at each
Roll level. As illustrated:

• The first level (sales representatives) aggregates credits into primary measurements.
• The second level (sales managers) aggregates primary measurements into secondary measurements.
• The third and fourth levels (district managers and Western Director, respectively) aggregate secondary
measurements into secondary measurements.

You can simplify your plans greatly by summing related measurements instead of credits up a Roll hierarchy.

 Note

If you need to show per-credit commissions at the higher levels of the Rollup hierarchy, you must use Rollup
credits instead of aggregating measurements.

Incentive Management Admin Design Guide

Formulas PUBLIC 193
14.6 Creating a Formula

You can create a formula either directly in the Formulas workspace, or by clicking the Formula button to open
the Formula editor.

You use the formula editor in two ways: 1) to create formulas and save them with a name, or 2) to create
formulaic expressions. A formulaic expression is used only by the current rule object. A saved formula can
be reused by other rule objects (rules or rule elements). A saved formula can be created from the Formulas
workspace, as described below, or the from the Formula editor. Large expressions or formulas should be split
into multiple formulas, for performance and readability reasons. For example, if you have a formula that uses
over 20 operators, if you split it into two formulas it is easier to read and is processed faster.

Procedure

1. Navigate to Compensation Elements > Formulas .

2. Choose Create).
3. Select a calendar and specify the effective dates for the new formula.
4. Enter formula name in the detail panel. The Summary panel immediately reflects with your entry. The
formula name entered here can be referenced in rules, rule elements, and other formulas.
5. (Optional) Enter a text description for the formula. If your organization has created and implemented
business units, you can assign this formula to one or more business units by selecting from the Business
Units drop-down. You can only select business units to which you as a user have been assigned.
6. Select the Return Type for the formula. Available return types are the base unit types, plus other common
values such as Boolean, currency, date, percent, quantity, integer, and string.
7. Construct the expression by selecting from the list of legal moves. The legal moves that are listed are those
that are appropriate to the return type specified for the formula or expression in the Formula edit pane.
8. Choose an item to edit it.
9. When applicable, double-click an underlined item to open a secondary editor dialog box. In the Formula
Edit pane. The system highlights incomplete or inappropriate element.
10. Complete the details in the Formula Edit panel if you select a Function from the list of legal moves.
The Function Info pane (right, grey pane) shows the detail for the selected function, including a brief
description of each parameter.
11. Use any of the following techniques to manipulate the parts of a formula:
• To insert an element into an expression, click the data element that is to the right of where you want to
insert something. Select the element(s) from the list of legal moves.
• To add an element, either double-click it in the list of legal moves or type * to bring up a list of data
fields and functions. You can also start typing the name of the item, and the system either fills in the
rest of the name (if there is only one item by that name) or provides a list of items that begin with that
name.
• To delete an element from an expression, select the element and press Delete or Backspace (deletes
items to the left of the selection).
• To replace a data element, select and delete it, and then select the item from the list of legal moves. To
change a function parameter, select the parameter and then replace it by selecting the parameter from
the Legal Moves listing.

Incentive Management Admin Design Guide

194 PUBLIC Formulas
 • If the original item is a value and you need to change the value, double-click the item and type the new
value.
• To replace a literal value with a placeholder, select the literal value (such as a precise calendar date of
September 27, 2008), and select the placeholder from the list of legal moves (for example, select the
Transaction.Compensation Dateitem).
12. Choose Save to save the formula.

14.7 Editing a Formula

To edit a formula involves any of the following operations:

• Renaming a formula.
• Add or remove a rule element (formula, variable, fixed value, rate table, territory, or lookup table).
• Change the return type of the formula.
• Add, remove, or change any of the parts of the formula that contribute to how the formula calculates its
results.
• Change the effective dates of the formula.

 Note

You cannot change the formula’s calendar. You must instead create a new formula. Currently, the
association between a calendar and a formula cannot be broken or changed.

Be aware that when you edit a formula, you edit the specified version of the formula. For example, you have a
formula that is effective from February 2008 to the End Of Time. If, however, in August 2008 you change how
the formula calculates, it is important to know the effective dates of the change. If, for example, to back-date
a change effective to February 2008, then you edit the current version of the formula (click Manage Versions
in the Formulas workspace). However, to make the changes effective from August 2008 to the End Of Time,
create a new version of the formula, and make the changes to that new version (click New Version in the
Formulas workspace). If you have a formula that is no longer effective, you change the effective end date of the
formula to the required date. Do not delete a formula if the formula was valid for any point in time.

14.8 Deleting a Formula

You can delete a formula that was just created either manually. You cannot delete a formula that is referenced
by a rule or a rule element. To delete such a formula, first change or remove the condition or action that
references the formula. Deleting a formula removes all versions of the formula object from the system.
However, the audit log in the Audit Log workspace retains information on the actions performed on the formula
object, including its remove (delete) date, and information about the objects themselves.

 Note

To delete a particular version of a formula, use Manage Versions on the toolbar.

Incentive Management Admin Design Guide

Formulas PUBLIC 195
14.9 Finding Objects Related to Formulas

You can find data related to one or more selected formulas by selecting the appropriate object option from the
Related pane.

Procedure

1. Navigate to Compensation Elements > Formulas .

2. Select a formula or formulas for which you need to find related objects in the Summary panel.
3. Select an object option, for example, Plans in the Related pane.
• If you are searching for related plans, the plans are retrieved immediately and the results are displayed
in the Plan workspace. If no results are found, the message “No Records Found.” is displayed in the
summary view panel.
• If you are searching for an object other than plans, the Search for Advanced Related Objects dialog with
the name of the selected object substituted for the object name.

The available options and data returned are as follows:

• Rules—returns the rules referring to the selected formula.

• Referring Formulas—returns the formulas referring to the selected formula.
• Referred Formulas—returns the formulas referred to by the selected formula.
• Referred Fixed Values—returns the fixed values referred to by the selected formula.
• Referring Rate Tables—returns the rate tables referring to the selected formula.
• Referred Rate Tables—returns the rate tables referred to by the selected formula.
• Referred Variables—returns the variables referred to by the selected formula.
• Referred Lookup Tables—returns the lookup tables referred to by the selected formula.
• Referring Lookup Tables—returns the lookup tables referring to the selected formula.
• Quotas—returns the quotas referred to by the selected formula.
• Plans—returns the plans that are referring to the rules which are referring to the selected formula.

Incentive Management Admin Design Guide

196 PUBLIC Formulas
15 About Variables

A variable is a placeholder in a rule or formula for a fixed value, rate table, or territory. You can assign a rule
element directly to the variable, the plan, the title, or to the position. You either create the variable first and then
use it in a rule, or create the variable while you are editing the rule. If you use variables, you must populate the
variable with a default element.

Related Articles

• Variable Assignments [page 197]

• Variable Workspace [page 198]
• Creating Variables [page 199]
• Editing Variables [page 202]
• Finding Objects Related to Variables [page 203]
• Assigning Rule Element to Variables [page 204]

15.1 Variable Assignments

You can assign default values to variables at different levels: at the variable level, at the plan level, at the title
level, and at the position level. The plan default overrides that of the variable, the title variable default overrides
that of the plan or the variable level, and the position variable default overrides all other defaults.

• A rule element assigned to a variable at the position level applies to only that specific position (overrides
the defaults at all other levels).
• A rule element assigned to a variable at the title level applies to all positions that use the title (overrides the
Plan and Variable defaults).
• A rule element assigned to a variable at the plan level applies to all positions assigned to the plan (overrides
the Variable defaults).
• A rule element assigned to the variable applies to all plans that include a rule that uses the variable.

The following figure illustrates how a variable can be assigned a different default value at different assignment
levels.

Incentive Management Admin Design Guide

About Variables PUBLIC 197
For example: in the rules in the Golf Product Sales Specialist plan there is a fixed value variable named
AnnualQuota_FVV. A default fixed value (representing a quota) can be assigned at the variable level; defaults
set at the variable level apply to wherever the variable is used, which could be multiple plans. A default fixed
value can also be assigned at the plan level, so that every position assignment assigned to the Golf Product
Sales Specialist plan uses the same quota, as a default. If the plan default is set, this overrides the default set at
the variable level.

If everyone associated with the Golf Product Sales Specialist title should use the same quota, a default fixed
value can be assigned at the title level. If the default is set at the title, this overrides any defaults specified at the
variable or plan levels. If it is preferred that each position assignment has a customized quota, then a default
fixed value can be assigned for each position. If the default is specified with the position, then this default
overrides any other specified defaults.

15.2 Variable Workspace

Navigate to Compensation Elements > Variables to access the Variables workspace.

The Variable workspace contains two panels:

• Variable Summary
• Variable Details (General Information and Associations)

Incentive Management Admin Design Guide

198 PUBLIC About Variables
Variable Summary

You can create new variables, edit existing variables, and delete variables from the Variables Summary toolbar.

Variable Details

You can edit details in the General Information tab. You can view the rules that use the variable from the
Associations tab. You can also view the elements associated with the variable.

15.3 Creating Variables

You can create variables in the Compensation Elements > Variables workspace.

Quick Links

• Creating a Fixed Value Variable [page 200]

• Creating a Rate Table Variable [page 200]
• Creating a Territory Variable [page 201]
• Creating a Lookup Table Variable [page 201]

Incentive Management Admin Design Guide

About Variables PUBLIC 199
15.3.1 Creating a Fixed Value Variable

You can create a fixed value variable to customize the fixed value that is used, at either the plan, title, or
position. A fixed value variable is a placeholder for a fixed value. You can assign a default to the fixed value
variable, and override that default at the plan, title, or position level. In cases when you are assigning a fixed
value to a fixed value variable and the variable has a period type specified, the period type of the fixed value and
variable must match. You cannot assign a fixed value without a period type to a fixed value variable that has a
period type specified.

Procedure

1. Navigate to Compensation Elements > Variables.

2. Choose Create.
3. In the popup, select a different calendar, specify new effective dates, and select Fixed Value from the Type
drop-down.
4. Enter a unique name for the fixed value variable. The fixed value variable name that you define here is
the one you specify later when including the variable in a rule or formula. If your organization has created
and implemented business units, you can assign this variable to one or more business units by selecting
from the Business Units drop-down. You can only select business units to which you as a user have been
assigned.
5. (Optional) Enter text description for the variable.
6. Select a Return Type as a base unit type of the fixed value variable.
7. (Optional) Specify a Default fixed value for this variable. You can override this default at the plan, title, or
position levels.
8. Select a Required Period Type to make the variable accept only fixed values of a specific period type.
9. Choose Save.

15.3.2 Creating a Rate Table Variable

You can create a rate table variable to customize the rate table that is used, at either the plan, title, or position.
A rate table variable is a placeholder for a rate table. You can assign a default to the rate table variable, and
override that default at the plan, title, or position level.

Procedure

1. Navigate to Compensation Elements > Variables.

2. Choose Create
3. In the popup, select a different calendar, specify new effective dates, and select Rate Table from the Type
drop-down.
4. Enter a unique name for the rate table variable. The rate table variable name that you define here is the
one you specify later when including the variable in a rule or formula. If your organization has created

Incentive Management Admin Design Guide

200 PUBLIC About Variables
 and implemented business units, you can assign this variable to one or more business units by selecting
from the Business Units drop-down. You can only select business units to which you as a user have been
assigned.
5. (Optional) Enter a text description of the variable.
6. Select an Input Type. The input type is the unit type of the attainment tiers in the rate table.
7. Select a Return Type. The return type is the unit type of the rates stored in the rate table.
8. Choose Save.
9. (Optional) Specify Default Rate Table for this variable. You can override this default at the plan, title, or
position levels.

15.3.3 Creating a Territory Variable

You can create a territory variable to customize the territory that is used, at either the plan, title, or position. A
territory variable is a placeholder for a territory. You can assign a default to the territory variable, and override
that default at the plan, title, or position level.

Procedure

1. Navigate to Compensation Elements > Variables.

2. Choose Create.
3. In the popup, select a different calendar, specify new effective dates, and select Territory from the Type
drop-down.
4. Enter a unique name for the territory variable. The territory variable name that you define here is the
one you specify later when including the variable in a rule or formula. If your organization has created
and implemented business units, you can assign this variable to one or more business units by selecting
from the Business Units drop-down. You can only select business units to which you as a user have been
assigned.
5. (Optional) Enter a text description of the variable.
6. (Optional) Specify a default territory to satisfy this territory variable. You can override this default at the
plan, title, or position levels.
7. Choose Save.

15.3.4 Creating a Lookup Table Variable

You can create a lookup table variable to customize the lookup table that is used, at either the plan, title, or
position. A lookup table variable is a placeholder for a lookup table. You can assign a default to the lookup table
variable, and override that default at the plan, title, or position level. The effective date range of lookup table
variables must be greater than or equal to the effective date range of the lookup table that is assigned as the
default. Once a lookup table variable has been used in a rule element, it cannot be modified.

Unlike other types of variables, you must specify a default value for a lookup table variable. The structure
(return type and number and types of dimensions and in the same order) of this default predetermines the

Incentive Management Admin Design Guide

About Variables PUBLIC 201
structure of the lookup table. In other words, if the default lookup table has a return type of USD and two
dimensions, with dimension type of string and numeric range respectively, then only lookup tables with this
same structure can be assigned to the lookup table variable. However, different versions of a lookup table
variable can have different structures. It is, therefore, possible to create a new version if a new structure if
needed.

Procedure

1. Navigate to Compensation Elements > Variables.

2. Choose Create.
3. In the popup, select a different calendar, specify new effective dates, and select Lookup Table from the
Type drop-down.
4. Enter a unique name for the lookup table variable. The lookup table variable name that you define here is
the one you specify later when including the variable in a rule or formula. If your organization has created
and implemented business units, you can assign this variable to one or more business units by selecting
from the Business Units drop-down. You can only select business units to which you as a user have been
assigned.
5. (Optional) Enter a text description of the variable.
6. Specify a default lookup table to satisfy this lookup table variable.
7. Choose Save.

15.4 Editing Variables

You can edit manually created variables in the Variables workspace. When editing variables in the system, you
can update the following options:

• Name
• Business Unit
• Description
• Required Period Type
• Default

Procedure

1. Navigate to Compensation Elements > Variables.

2. Choose Edit to update the variable details.
3. Add new information in the available fields.
4. Choose Save.

Incentive Management Admin Design Guide

202 PUBLIC About Variables
15.5 Deleting a Variable

You can delete a variable that was just created manually in UI. You cannot delete a formula that is referenced
by a rule or a rule element. You can also select variables of different types (fixed value variables, rate table
variables, lookup table variables, and territory variables) and delete them if all the variables selected do not
have related results data and are not referred to by other objects.

When you multi-select variables of different types, no information is displayed in the detail pane. Deleting a
variable removes all versions of the variable object from the the system; however, the audit log in the Audit Log
workspace retains information on the actions performed on the variable object, including its remove (delete)
date, and information about the object itself.

 Note

To delete a particular version of a variable, use the Manage Versions option in the Ellipsis Menu (…).

15.6 Finding Objects Related to Variables

You can find data related to one or more selected variables by selecting the appropriate object option from the
Related pane.

Procedure

1. Navigate to Compensation Elements and choose the variable you want to find objects for.
2. Search for the variable or variables for which you want to find related data if required.
3. Select the variable or variables In the Summary view.
4. Choose the Related panel and select an object option, for example, Rules.

• If you are searching for related plans, positions, titles, fixed values, rate tables, territories, or lookup tables,
the objects are retrieved immediately and the results are displayed in the related workspace. If no results
are found, the message “No Records Found.” is displayed.
• If you are searching for related rules, referring to formulas, or referring lookup tables, the Search For
Advanced Related Objects dialog displays with the name of the selected object substituted for the object
name.

The available options and data returned are as follows:

• Rules: returns the rules referring to the selected variable.

• Referring Formulas: returns the formulas referring to the selected variable.
• Referring Lookup Tables: returns the lookup tables referring to the selected variable.
• Plans: returns the plans referring to the selected variable.
• Positions: returns the positions referring to plans that have rules referring to the selected variable.
• Titles: returns the titles referring to plans that have rules referring to the selected variable.

Incentive Management Admin Design Guide

About Variables PUBLIC 203
• Fixed Values: returns the following:
• Fixed values used in the variable assignment for the fixed value variable regardless of whether the variable
assignment is by plan, title, or position.
• If a default fixed value was assigned to the fixed value variable, returns that fixed value.
• Rate Tables: returns the following:
• Rate tables used in the variable assignment for the rate table variable regardless of whether the
variable assignment is by plan, title, or position.
• If a default rate table was assigned to the rate table variable, returns that rate table.
• Territories: returns the following:
• Territories used in the variable assignment for the territory variable regardless of whether the variable
assignment is by plan, or title or position.
• If a default territory was assigned to the territory variable, returns that territory.
• Lookup Tables: returns the following:
• Lookup tables used in the variable assignment for the lookup table variable regardless of whether the
variable assignment is by plan, title, or position.
• If a default lookup table was assigned to the lookup table variable, returns that lookup table

15.7 Assigning Rule Elements Overview

When working with Territory, Fixed Value, and Rate Table variables, the default value that is used in rules
depends on the level (variable, plan, title, or position) at which the default is specified. Variables specified at the
Position level taking precedent over variables specified at the title or plan levels. The following table describes
the order of precedence used to determine which default is used. Because you can only specify a default for a
Lookup Table at the variable level, these default precedences do not apply.

Variable Default Assignments:

Default Level Description Display

Variable Applies wherever the variable is used. Element name (variable)

Plan Applies to each place the variable is Element name (plan)

used on the specified plan.

Overrides any default specified at the

variable.

Incentive Management Admin Design Guide

204 PUBLIC About Variables
Default Level Description Display

Title Applies to each place the variable is Element name (title)

used on a plan that is assigned to the
specified title.

Overrides any default specified at the

variable or plan levels.

Position Applies to each place a variable is used Element name (position)

on a plan associated with the specified
position.

Overrides any default specified in the

variable, plan, or title levels.

When viewing what elements are assigned to variables, if an element is assigned to the variable at the plan
level when you view the list of assignable items at the position or title level, the plan level variable assignment
displays with “(plan)” next to it. The same is true for when an item is assigned at the title level, and you are
viewing the item at the position level.

 Note

When viewing the plan, you can assign elements to variables at the position or title levels. Follow the same
procedure as for assigning at the plan level, but in the list of assignments, select either the title or the
position instead of the default. (If the position is associated with the plan by way of a title assignment, the
position is not specifically listed here).

Related Articles

• Assigning or Removing a Lookup Table [page 205]

• Assigning or Removing a Territory [page 206]
• Assigning or Removing a Rate Table [page 207]
• Assigning or Removing a Fixed Value [page 208]

15.7.1 Assigning or Removing a Lookup Table

You can assign a lookup table to a variable at the plan level. You can also assign a lookup table to a variable
at the position, title, or variable levels. You perform those operations from the Positions, Titles, or Variables
workspaces. You can also select a position or title in the Assignments tab of the Plans Wizard workspace to do
position and title variable assignments.

Incentive Management Admin Design Guide

About Variables PUBLIC 205
Assign Lookup Table to Plan’s Lookup Table Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select a plan. The plan must contain a rule that uses a lookup table variable.
3. Choose the Assignments tab if required.
4. Select Default in the list of Assignable items. Default refers to the assignment at the plan level.
5. Selecy the area in the Rule Element column that corresponds to the lookup table variable to which you
want to assign a lookup table.
6. Specify a Lookup Table.
7. Choose Save to save the changes. The lookup table is now assigned to the variable at the plan level.

Remove Lookup Table Assignment to Lookup Table Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select a plan.
3. Choose the Assignments tab.
4. Select Default in the list of the assignable items. Default refers to the assignment at the plan level.
5. Select the Lookup Table that is assigned to the territory variable.
6. Click Save. The system removes the plan-level assignment of the lookup table to a lookup table variable.
If the variable has a default lookup table set, then the variable-level lookup table is now the default. The
variable assignment displays with “(lookup table variable)” after it. If there is a lookup table assigned to the
variable at either the title or position levels, those assignments continue to override any defaults set at the
variable or plan levels.

15.7.2 Assigning or Removing a Territory

You can assign a territory to a variable at the plan level. You can also assign a territory to a variable at
the position, title, or variable levels. You perform those operations from the Positions, Titles, or Variables
workspaces. You can also select a position or title in the Assignments tab of the Plan Wizard workspace to do
position and title variable assignments.

Assign Territory to Plan’s Territory Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select the plan. The plan must contain a rule that uses a territory variable.
3. Choose the Assignments tab.
4. View Variable assigned by, select Default in the list of Assignable items. Default refers to the assignment at
the plan level.
5. Choose the area in the Rule Element column that corresponds to the territory variable to which you want to
assign a territory.

Incentive Management Admin Design Guide

206 PUBLIC About Variables
6. Specify a territory.
7. Enter to complete the change
8. Choose Save to save the changes.The territory is now assigned to the variable at the plan level.

Remove Territory Assignment to Territory Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select the plan.
3. Choose the Assignments tab.
4. Select Default in the list of Assignable items (View Variable assigned by). Default refers to the assignment
at the plan level.
5. Select the territory that is assigned to the territory variable.
6. Choose Save. The sytsem removes the plan-level assignment of the territory to a territory variable. If
the variable has a default territory set, then the variable-level territory is now the default. The variable
assignment displays with “(territory variable)” after it. If there is a territory assigned to the variable at
either the title or position levels, those assignments continue to override any defaults set at the variable or
plan levels.

15.7.3 Assigning or Removing a Rate Table

You can assign or remove a rate table to a variable at the plan level. You can also assign a rate table to a variable
at the position, title, or variable levels. You perform those operations from the Positions, Titles, or Variables
workspaces. You can also select a position or title in the Assignments tab of the Plans Wizard workspace to do
position and title variable assignments.

Assign Rate Table to Plan’s Rate Table Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select a plan. The plan must contain a rule that uses a rate table variable.
3. Choose the Assignments tab.
4. Select Default in the list of Assignable items (View Variable assigned by). The Default refers to the
assignment at the plan level.
5. Select the area in the Rule Element column that corresponds to the rate table variable to which you want to
assign a rate table.
6. Specify a rate table. When choosing an existing rate table, the system displays a list of rate tables that are
appropriate to the input type and return type for the rate table variable.
7. Choose OK to complete the change, and choose Save to save the changes. The rate table is now assigned
to the variable at the plan level.

Incentive Management Admin Design Guide

About Variables PUBLIC 207
Remove Rate Table Assignment to Rate Table Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select the plan.
3. Click the Assignments tab.
4. Select Default in the list of Assignable items(View Variable assigned by). The Default refers to the
assignment at the plan level.
5. Select the rate table that is assigned to the rate table variable.
6. Click Save. The system removes the plan-level assignment of the rate table to a rate table variable. If
the variable has a default rate table set, then the variable-level rate table is now the default. The variable
assignment displays with “(rate table variable)” after it. If there is a rate table assigned to the variable at
either the title or position levels, those assignments continue to override any defaults set at the variable or
plan levels.

15.7.4 Assigning or Removing a Fixed Value

You can assign or remove a fixed value assignment to a variable at the plan level. You can also assign a fixed
value to a variable at the position, title, or variable levels; you perform those operations from the Positions,
Titles, or Variables workspaces. You can also select a position or title in the Assignments tab of the Plan
workspace to do position and title variable assignments.

Assign Fixed Value to Plan’s Fixed Value Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select a plan. The plan must contain a rule that uses a fixed value variable.
3. Choose the Assignments tab.
4. Select Default in the list of Assignable items. The Default refers to the assignment at the plan level.
5. Select the area in the Rule Element column that corresponds to the fixed value variable to which you want
to assign a fixed value. If a fixed value variable has a required period type specified, that period type is
listed along with the name of the variable in the list of assignable items.
6. Specify a fixed value. When choosing an existing fixed value, the system displays a list of fixed values that
are appropriate to the return type and period type, if necessary, for the fixed value variable.
7. Choose Ok to complete the change, and choose Save to save the changes. The fixed value is now assigned
to the variable at the plan level.

Remove Fixed Value Assignment Fixed Value Variable at Plan Level

1. Navigate to Plan Data > Plans Wizard.

2. Select the plan.
3. Choose the Assignments tab.

Incentive Management Admin Design Guide

208 PUBLIC About Variables
4. Select Default in the list of Assignable items. The Default refers to the assignment at the plan level.
5. Select the fixed value that is assigned to the fixed value variable,
6. Choose Save. The system removes the plan-level assignment of the fixed value to a fixed value variable. If
the variable has a default fixed value set, then the variable-level fixed value is now the default. The variable
assignment displays with “(fixed value variable)” after it. If there is a fixed value assigned to the variable at
either the title or position levels, those assignments continue to override any defaults set at the variable or
plan levels.

Incentive Management Admin Design Guide

About Variables PUBLIC 209
16 About Territories

A territory is a named group of categories and classifiers that are used to filter input to credit and
measurement rules. Although the name territory implies geographical location, territories can include
categories and classifiers that are associated with products and customers as well as postal codes and other
custom classifier types. Territories are used in credit rules to determine who gets credit for a transaction.
Territories are also used in measurement rules to determine how credits are aggregated. You define a territory
using categories. A simple territory can use a single category or classifier in its definition. For example, you can
define a territory strictly based on the products that a salesperson sells.

A complex territory can combine several categories, or parts of category hierarchies, together in its definition.
For example, a complex territory can be defined as a mix of products, geographical locations, and industries.
When you create a territory you can tie multiple categories and classifiers together with 'And' and 'Or' logic
(Boolean). Negative ('not') logic is also available for excluding specific things from a larger grouping.

Related Articles

• Territory Workspace [page 210]

• Creating a Territory [page 212]
• Editing a Territory [page 213]
• Deleting a Territory [page 213]
• Finding Objects Related to Territories [page 213]

16.1 Territory Workspace

Navigate to Compensation Elements > Territories to access the Territories workspace.

The Territories workspace contains two panels:

• Territory Summary
• Territory Details (General Information and Associations)

Territory Summary

You can create new variables, edit existing variables, and delete variables from the Territories Summary toolbar

Incentive Management Admin Design Guide

210 PUBLIC About Territories
In the territory definition (Expression)area, you can define your territories by selecting components from the
Legal Moves pane. You can use the logical operator buttons to join or combine territory criteria; you can use
and, or, not, in addition to creating parenthetical statements. The system processes the logical operators
of and, or in the order in which they display unless they are in parenthetical statements. For example, the
following example of:

Golf Putter AND Named Account OR Area Code 831 is processed as

[(Golf Putter AND Named Account) OR Area Code 831]

 Note

You can copy and paste territory definitions between territories. To do so, select a territory, double-click
the definition to select it, use Ctrl + C to copy it; then in the target territory, use Ctrl + V to paste it.

If you use multiple categories to create a territory, construct the territory definition to maximize processing
efficiency. The system evaluates territories from the top down. After the territory evaluation succeeds (finds a
match), it stops evaluating and goes on to the next step in the rule.

• For an and condition, both parts must be true for the territory to succeed. List the clause that is most likely
to fail first. If it fails, the rule engine stops evaluating and moves on. If you put the clauses in the other order,
most likely to succeed, then the rule engine must go on to evaluate the second clause.
• For an and condition, thel match succeeds if either clause is true. List the clause that is most likely to
succeed first. If it succeeds, the rule engine stops evaluating sooner and moves on to the rest of the rule.

Territory Details

You can edit details in the General Information tab. From the Associations tab, you can view the rules that use
the territory and the elements associated with the territory.

Incentive Management Admin Design Guide

About Territories PUBLIC 211
16.2 Creating a Territory
You can create simple territories that include a single category and its classifiers or a complex territory that
includes or excludes categories and classifiers based on certain conditions. Although you can create territories
that do not have associated categories and classifiers and even include these territories in rules, transactions
associated with these territories are not classified.

Procedure

1. Choose Compensation Elements > Territories.

2. Choose Create.
3. Specify the effective dates for the new territory. This creates a new empty territory.
4. Enter a unique name for the territory in the details panel. The territory name is used when assigning
the territory rule element to a plan. The Summary panel immediately reflects with your entry. If your
organization has created and implemented business units, you can assign this variable to one or more
business units by selecting from the Business Units drop-down. You can only select business units to which
you as a user have been assigned.
5. (Optional) Enter a text description of the territory.
6. Select the Show Category Hierarchies option to display the Category Hierarchy panel.
7. Specify the item(s) by performing any of the following:
• Search by name—Type the beginning text of an existing subcategory or classifier, select an item from
the list, and press Return to add the item to the territory definition.
• Search by name—Type * to get a list of all subcategories or classifiers, select an item from the list that
pops up, and press Return to add the item to the territory definition.
• Search by category location—In the right pane, locate and select the subcategory or classifier, and
choose Add to add the item to the territory definition.
• For an AND statement, put first the element that is the most likely to fail. For example, AreaCode=408
‘and’ Product=Golf Clubs.
• For an OR statement, put first the element that is the most likely to succeed. For example,
Channel=Direct ‘or’ Product=Golf Pro Sets
• You can use Ctrl-click and Shift-click to select multiple categories. After you choose Add, the system
prompts you for the logical operator to combine the selected items.
• To combine multiple category criteria, use the logical operators. Type * to get a list of all applicable
logical operators. You can also directly type any logical operator. (Note that <> is “not equal to”). In
both cases, processing time is not spent evaluating the second element.
• To rearrange a territory definition, you can use copy and paste (right-click and select the edit operation
from the context menu).
• Use any of the following techniques to manipulate the parts of a territory:
• To change a category or classifier in a territory expression: The Territory Expression area, select the
item you want to change and then press Delete. Select another category item, and choose Add to add
the replacement item.
• To change the logic that joins multiple categories: Select the operator item in the Territory Definition
area, and then choose Delete. Choose one of the available logical operator buttons to replace the
deleted operator.

Incentive Management Admin Design Guide

212 PUBLIC About Territories
8. Choose Save.

16.3 Editing a Territory

To edit a territory involves any of the following operations:

• Rename the territory

• Add, remove, or change the territory’s description
• Change the territory’s expression
• Change the effective dates of the territory

Be aware that when you edit a territory, you edit the specified version of the territory. For example, say you
have a territory that is effective from May 2008 to the End Of Time. If, however, in September 2008 you change
how the territory calculates, it is important to know the effective dates of the change. If, for example, you
back-date changes to May 2008, then you edit the current version of the territory (click Manage Versions in the
Territories workspace). However, to make changes effective from September 2008 to the End Of Time, create a
new version of the territory, and make the changes to that new version (click Manage Versions in the Territories
workspace). If you have a territory that is no longer effective, you change the effective end date of the territory
to the required date. You do not do a delete operation if the territory was valid for any point in time.

16.4 Deleting a Territory

You can delete a territory that was just created either manually or using XML import. You cannot delete a
territory that is referenced by a rule or rule element or is assigned to a territory variable. Deleting a territory
removes all versions of the territory object from the the system; however, the audit log in the Audit Log
workspace retains information on the actions performed on the territory object, including its remove (delete)
date, and information about the object itself.

 Note

To delete a particular version of a territory, use the Manage Versions option in the Ellipsis Menu (…).

16.5 Finding Objects Related to Territories

You can find data related to one or more selected territories by selecting the appropriate object option from the
Related panel.

Incentive Management Admin Design Guide

About Territories PUBLIC 213
Procedure

1. Choose Compensation Elements > Territories.

2. Search for the territories for which you want to find related data.
3. Select territory or territories in the Summary panel.
4. Select object option, for example, Rules in the Related panel.

• If you’re searching for related plans, the plans are retrieved immediately and the results are displayed in the
Plan workspace. If no results are found, the message No Records Found is displayed.
• If you’re searching for related rules, titles, positions, or referring variables, the Search for Advanced Related
Objects dialog displays with the name of the selected object substituted for the object name.

The available options and data returned are as follows:

• Rules—returns the rules that are referring to the selected territory.

• Positions—returns the positions that have the selected territory in the position variable assignment.
• Titles—returns the titles that have the selected territory in the title variable assignment.
• Referring Variables—returns the variables that have the selected territory as their default.
• Categories—returns the categories referred to by the selected territory.
• Plans—returns the following:
• Plans that are referring to the rules that are directly using the selected territory.
• Plans that have the selected territory in the plan variable assignment.

Incentive Management Admin Design Guide

214 PUBLIC About Territories
17 Fixed Values Overview

Fixed values might or might not be period based. A fixed value that is not period based can be used to store a
single, reusable value. A period-based fixed value can be used to store reusable values for each leaf-level period
within a specified date range. For example, a period-based fixed value can store, for each month, a participant’s
performance percentage. A fixed value can also store a commission rate, a target amount, or a counter for the
number of product types sold.

Fixed Value Types are an optional attribute you can create and then apply to groups of fixed values. If you want
to organize your fixed values by type, you can create and assign a fixed value type to a selection of fixed values.
For example, you could create fixed value types for Quotas, Commission Rates, and Counters. You can use a
fixed value wherever a value is called for—in a rule, in a field on a participant or position, or in a formula, rate
table, lookup table, or another fixed value. You can use a fixed value inside of a variable or you can use a fixed
value directly.

In cases when you are assigning a fixed value to a fixed value variable and the variable has a period type
specified, the period type of the fixed value and variable must match. You cannot assign a fixed value without
a period type to a fixed value variable that has a period type specified. Fixed values have a unique name and
period type combination. For example, you can create three fixed values, each with the same name but each
with a different period type, such as year, quarter, and month. You can also create a fixed value with the same
name and not specify a period type.

You can use a fixed value directly in a compensation rule, or you can use a fixed value variable in the rule and
then assign the fixed value to the variable.

Related Articles

• Fixed Values and Effective Dates [page 215]

• Using a Fixed Value or Quota [page 216]
• Fixed Values and Quotas [page 216]
• Fixed Value Workspace [page 216]
• Creating a Fixed Value [page 218]
• Editing Fixed Values [page 219]
• Deleting a Fixed Value [page 219]
• Finding Objects Related to Fixed Values [page 220]

17.1 Fixed Values and Effective Dates

Here are some notes about working with fixed values:

• You cannot change the period type of a fixed value after you have entered values. If you want to change the
period type of a fixed value, you must create a new fixed value.

Incentive Management Admin Design Guide

Fixed Values Overview PUBLIC 215
• When selecting the periods to show using show values for, the system allows you to select the periods that
are of a higher level period type then the period type of the fixed value. For example, if the fixed value is
month-based, then you can show values for the quarters or years. For year-based fixed values, you can only
change what periods to show if you have a period type defined that is of a higher level thanyear, such as a
decade.
• When values are not entered in consecutive cells for fixed values, gap versions are created. These gap
versions are assigned null values.

17.2 Using a Fixed Value or Quota

If you want to set quota values for a group of positions unrelated in the reporting hierarchy, fixed values are a
better choice. Fixed values are also useful if you want to set default values at the variable, title, or plan levels.
If you want to manage quota values for a large portion of the organization from a single screen, quotas are a
better choice. You can view the quota values for an entire position hierarchy across multiple period types.

Related Information

Fixed Values and Quotas [page 216]

17.3 Fixed Values and Quotas

Fixed values cannot be used in a quota object. In cases where a rule or rule function asks for a quota value,
you can specify either a literal value, a fixed value, a fixed value variable, or a quota object. For example, a
commission rule uses a value in a field labeled “quota” to calculate the commission. In this quota field, you can
specify a literal value, a fixed value, a fixed value variable, or a quota object.

Related Information

Using a Fixed Value or Quota [page 216]

17.4 Fixed Values Workspace

Navigate to Compensation Elements > Fixed Values to access the Fixed Values workspace.

The Fixed Value workspace contains two different panels:

Incentive Management Admin Design Guide

216 PUBLIC Fixed Values Overview
• Fixed Value Summary
• Fixed Value Details (General Information and Associations)

Fixed Value Summary

The following figure shows the Fixed Value tab. When you select a period type, the right side of the detail pane
changes to reflect your selection. The selection of month is reflected. If no period type is selected, the right
side of the detail pane remains blank.
You can create new fixed values, edit existing fixed values, and delete fixed values from the Fixed Values
Summary toolbar.

 Note

When you select a period based fixed value in the summary pane, the system displays only the value
associated with the default period in the summary record. For example, if you select the Sales Associate
Monthly fixed value and the default period is January 2008, the value for January 2008 is displayed. This is
because the summary pane can only show one value.

Fixed Value Details

You can edit details in the General Information tab. From the Association tab of the Fixed Values workspace,
you can view the rules that use the fixed value and the elements associated with the fixed value.

Incentive Management Admin Design Guide

Fixed Values Overview PUBLIC 217
17.5 Creating a Fixed Value

Create a fixed value for a value that you want to store and reuse, such as a quota or a currency conversion rate.
You can copy fixed values, as long as you give the new fixed value a unique name and period type.

Procedure

1. Choose Compensation Elements > Fixed Values.

2. Choose Create.
3. Specify the calendar and effective dates for the new fixed value. The system creates a new, empty fixed
value.
4. In the detail pane, enter a unique name for the fixed value. The fixed value name that you define here is the
one you specify later when you assign the fixed value to a rule or formula either directly, or by way of a fixed
value variable. The summary pane immediately reflects your entry.
5. If your organization has created and implemented business units, you can assign this fixed value to one or
more business units by selecting from the Business Units drop-down. You can only select business units to
which you as a user have been assigned.
6. (Optional) Enter a description for the fixed value.
7. (Optional) If fixed value types have been created by the administrator, select a Fixed Value Type.
8. (Optional) Select a Period Type. If you select a period type, the fixed value is period-based and you can
enter values for each of the leaf-level periods. Each period value is treated internally as a separate fixed
value version.
• The available periods are dependent on the calendar specified for the fixed value. For example, if you
have specified the Main Monthly Calendar, you can select month, quarter, year, or decade. In the
following example, quarter was selected.
• Values for each period can be entered in the fixed values pane on the right. If the same value is required
for several periods, you can choose Manage Versions to access the Versions for Object dialog. Entering
a value for the first leaf-level period cascades the value down. You can also use Manage Versions to
create versions within a particular leaf period by selecting the New field button. For example, if you are
using a “quarter? period type, you can actually create a version for a month within that quarter. In the
fixed values pane a quarter that contains one or more monthly versions displays as Various
• If you do not specify a period type, then the fixed value that is created is a single, effective-dated value.
Additional versions can be created by using the New Versions button.
• If you do not specify a period type, then the fixed value that is created is a single, effective-dated value.
Additional versions can be created by using the New Versions button.
If no period type was selected, enter a number in the Value field and choose the Unit Type field button
to select a unit type. The predefined unit types are USD, percent, integer, and number, but more can be
created.

 Note

Period-based fixed values can only be assigned to variables of the same period type.

9. If a Period Type was selected, you can optionally select a period from the Show values for the drop-down
list. You can select and display all periods associated with the calendar, or select and display only a specific

Incentive Management Admin Design Guide

218 PUBLIC Fixed Values Overview
 period or range of periods. For example, if you selected a quarterly period type, you can select 2008 to
display the quarterly periods for 2008.
10. In the Fixed Values pane on the right, choose in the Fixed Values column and, for each period displayed,
enter a value then choose the Unit Type field button to select a unit type for that value.
11. Choose Save

17.6 Editing a Fixed Value

To edit a fixed value involves any of the following operations:

• Rename the fixed value

• Change the business unit of the fixed value
• Add, change, or remove the description of the fixed value
• Add, change, or remove the fixed value type associated with the fixed value
• Change the value or values, if the fixed value is period based, of the fixed value
• Change the effective dates of the fixed value

 Note

You cannot change the fixed value’s calendar. You must instead create a new fixed value. Currently, the
association between a calendar and a fixed value cannot be broken or changed.

Editing a period-based fixed value creates a new version of that fixed value. When you edit a fixed value that is
not period based, you edit the specified version of the fixed value. For example, you have a fixed value that is
effective from January 2008 to the End Of Time. If in February 2008 you change the fixed value’s value, it is
important to know the effective dates of the change. If, for example, you want the changes to be back-dated
effective to January 2008, then you edit the current version of the fixed value (click Manage Versions in the
Fixed Values workspace). If you want the changes to be effective from February 2008 to the End Of Time, then
you create a new version of the fixed value, and make the changes to that new version (click Manage Versions
in the Fixed Values workspace). If you have a fixed value that is no longer effective, you change the effective end
date of the fixed value to the desired date. Do not delete the fixed value if it was valid for any point in time.

17.7 Deleting a Fixed Value

You can delete a fixed value that was just created either manually or using import. You cannot delete a fixed
value that is referenced by a rule or rule element or is assigned to a fixed value variable. Deleting a fixed
value removes all versions of the fixed value object from the system; however, the audit log in the Audit Log
workspace retains information on the actions performed on the fixed value object, including its remove (delete)
date, and information about the object itself.

 Note

To delete a particular version of a fixed value, use the Manage Versions button on the toolbar.

Incentive Management Admin Design Guide

Fixed Values Overview PUBLIC 219
17.8 Finding Objects Related to Fixed Values

You can find data related to one or more fixed values by selecting the appropriate object option from the
Related pane. The available options and the data returned are as follows:

• Rules—returns the rules that are referring to the selected fixed value.

• Positions—returns the positions that have the fixed value in their position variable assignment.

• Titles—returns the titles that have the selected fixed value in their title variable assignment.

• Referring Formulas—returns the formulas that are referring to the selected fixed value.

• Referring Rate Tables—returns the rate tables that are referring to the selected fixed value.

• Referring Variables—returns the variables that have the selected fixed value as their default.

• Referring Lookup Tables—returns the lookup tables that are referring to the selected fixed value.

• Plans—returns the following:

• Plans that are referring to the rules that are directly using the selected fixed value.

• Plans that have the fixed value in their plan variable assignment.

To find objects related to fixed values:

1. Click Fixed Values from the Plan Data menu.

2. Search for the fixed value or fixed values for which to find related data If necessary.
3. Select the fixed value or fixed values in the Summary panel.
4. Select an object option, for example, Rules in the Related panel.

• If you are searching for related plans, the plans are retrieved immediately and the results are displayed in
the Plan workspace. If no results are found, the message No records Found is displayed.

• If you are searching for objects other than related plans, the Search for Advanced Related Objects dialog
displays with the name of the selected object substituted for the object name.

Incentive Management Admin Design Guide

220 PUBLIC Fixed Values Overview
18 Quotas Overview

Quotas are values that apply across an entire reporting structure, and you can manage the different values
from a single screen. You can select multiple period types, and perform automatic sum or distribute functions
to distribute the quota values across an organization. The main advantage of quotas is that you can manage
the quota values for a large portion of an organization from a single screen. You can view the quota values for
an entire position hierarchy across multiple period types. However, to set quota values for a group of positions
unrelated in the hierarchy, fixed values are a better choice. Fixed values are also useful if you need to set default
values at the variable, title, or plan levels. You can use a quota wherever a value is used, except in a fixed value
variable or in another quota. If you’re accustomed to using fixed values, there are some important things to
note about quotas:

• Quotas aren’t effective dated. Instead, they are effective from the beginning of time (01/01/1900) to the
End Of Time (1/1/2200). Quotas apply to all versions of a position.
• You cannot use a quota in a fixed value variable. When you use a quota in a rule or formula, you directly
reference the quota. Quotas do not have default values. If you do not specify a quota value for a position
and a period, during a calculation run that includes that period the rule that uses the quota does not
calculate a result for that position.

 Note

When values are not entered in consecutive cells for quotas, gap versions are created. These gap versions
are assigned null values.

Related Articles

• Quotas Workspace [page 221]

• Creating a Quota [page 222]
• Editing a Quota [page 223]
• Deleting a Quota [page 224]
• Quota Functions [page 225]

18.1 Quotas Workspace

Navigate to Compensation Elements > Quotas to access the Quotas workspace.

The Quotas workspace contains two different panels:

• Quota Summary
• Quota Details (General Information and Quota Values)

Incentive Management Admin Design Guide

Quotas Overview PUBLIC 221
Quota Summary

You can create new quotas, edit existing quotas, and delete quotas from the Quotas Summary toolbar.

Quota Details

You can edit details in the General Information tab. In Quota Values, to view a portion of the position hierarchy,
specify the top node you want to display. You can also view values for a specific period.

 Note

The description field can be disabled in the Quotas workspace.

18.2 Creating a Quota

To assign quota values to positions, your user account must have at least read permission to positions. If your
organization uses business units, the quota’s business unit assignment should match that of the associated
position. You cannot copy quotas. If you must duplicate a quota, you can export the quota to XML, edit the XML
file so that the quota uses a new name, and then import the quota XML.

Procedure

1. Choose Compensation Elements > Quotas.

2. Choose Create. The system do not prompt you for the effective dates for the new quota, as it does for other
objects because quotas are not effective dated.
3. Enter a unique name for the quota in the detail pane of the General Information tab. The Summary panel
immediately reflects your entry. The quota name that you define here is the one you specify later when you
use the quota in a rule or formula.
4. Specify the following information for the quota:

Field Description

Business Units If your organization has created and implemented business units, you can assign this quota to
one or more business units by selecting from the Business Units drop-down. You can only select
business units to which you as a user have been assigned.

Description (Optional) Enter a text description of the quota.

Incentive Management Admin Design Guide

222 PUBLIC Quotas Overview
 Field Description

Calendar Specify the calendar for this quota. This is the same calendar that the rules, formulas, and other
associated rule elements are associated with.

If necessary, you can define a different quota value for each period type.

Unit Type Specify the unit type for the values stored in the quota.

Period Type You must specify at least one period type for the quota. The period types available are those
defined in the associated calendar.

If there are values specified for a period type, you cannot modify the period type specification for
the quota.

Last Modified This is the date in which this specific record was last modified

5. Specify the following display options on the Quota Values tab in the detail view:

Field Description

Set Tree View Specify the node in the Reporting Structure to display for the quota. The Tree View Root is the
Root to starting point of the positions for the quota; all positions that report to the specified position are
included in the quota Value display.

If you do not specify a Tree View Root, the entire Reporting Structure displays.

Set Period View to Specify the range of periods that you want to display the quota values for. You can specify a
specific period of any type that is specified on the quota’s General Information tab.

For example, if you are using a standard calendar with months, quarters, and years, you can
specify a single month, a quarter, a year, or a decade to view the quota values for.

6. Enter the quota values. There are multiples options for entering values:
• Use the Find Position/Payee field to search for a specific position or participant. You can then directly
enter the quota amount in the cell or the Value field (next to the Find Position/Payee field).
• Calculate a value by using one of the quota functions.
• To enter the same value in multiple cells at a time, select the cells and enter the value in the Value field
(next to the Find Position/Payee field).
• If you do not enter a value in a quota cell, the system considers it to be the same as a zero value.
7. Choose Save.

18.3 Editing a Quota

You can edit and calculate values for a position reporting structure quickly and easily using either the Quota
Value tab in the Quotas workspace. You can select edit single values, or you can edit multiple cell values
simultaneously. You can also use the quota functions to calculate values based on the position hierarchy
or period levels. Use Ctrl + left-click to select non-adjacent cells. You can access the quota sum and
distribute functions either by right-clicking in a cell or clicking one of the function buttons.

Incentive Management Admin Design Guide

Quotas Overview PUBLIC 223
You cannot remove period types from a quota if the quota contains any values for that period type. For
example, if you have monthly values specified, you cannot remove the month period type from the quota. When
editing quota values for positions, be sure to edit values for the positions that are using the quota. The quota
must be used in a rule in the plan to which the positions are assigned. Otherwise, the quota is not used for any
compensation processing.

 Note

If a position is added into the hierarchy after you have calculated quota values, The system does not
automatically calculate the new position’s quota values.

When you first open an existing quota, the system displays the values according to the default period. For
example, if the system opens with a default period of January 2008, then the quota initially displays the values
for January 2008.

 Note

When editing quota values, two users cannot edit values for the same quota or for the same position at the
same time.

18.4 Deleting a Quota

You can delete a quota that was just created either manually or using import. You cannot delete a quota that
has related results data (a calculation run has not yet occurred for the associated plan and position). Deleting
a quota removes the quota and all its quota values from the system. However, the audit log in the Audit Log
workspace retains information on the actions performed on the objects, including their remove (delete) date,
and about the objects themselves.

Take extra caution when deleting quotas, as they are removed from the database. Quotas are not effective
dated, so it is a more drastic move to delete them (you cannot simply end-date them as you can objects that
are effective dated).

Incentive Management Admin Design Guide

224 PUBLIC Quotas Overview
18.5 Finding Objects Related to Quotas

You can find data related to one or more selected quotas by selecting the appropriate object option from the
Related pane.

Procedure

1. Choose Compensation Elements > Quotas.

2. Search for the quota or quotas for which to find related data.
3. Select the quota or quotas in the Summary panel.
4. Select Positions or Rules in the Related panel. The Search for Related Objects dialog displays with the name
of the selected object substituted for the object name.

The available options and data returned are as follows:

• Positions—Returns the positions that have quota values defined for the selected quota.
• Rules—Returns the rules that are directly referring to the selected quota.
• Referring Formulas—Returns the formulas referring to the selected quota.
• Referring Rate Tables—Returns the rate tables referring to the selected quota.
• Referring Lookup Tables—Returns the lookup tables referring to the selected quota.

18.6 Quota Functions Overview

A quota function is available for quotas. The quota functions are:

• Sum Subordinates
• Sum Leaf Subordinates
• Distribute to Subordinates
• Distribute to Leaf Subordinates
• Sum Sub-Periods
• Sum Leaf Sub-Periods
• Distributes to Sub-Periods
• Distributes to Leaf Sub-Periods

Related Articles

• Sum Subordinates [page 226]

• Sum Leaf Subordinates [page 226]

Incentive Management Admin Design Guide

Quotas Overview PUBLIC 225
• Distribute to Sub-Periods [page 227]
• Distribute to Leaf Subordinates [page 227]
• Sum Sub-Periods [page 227]
• Distribute to Sub-Periods [page 227]
• Distribute to Leaf Sub-Periods [page 228]
• Finding Objects Related to Quotas [page 225]

18.6.1 Sum Subordinates

The Sum Subordinates Quota function sums the values of the subordinates one level below the selected
position.

Related Information

Quota Functions Overview [page 225]

18.6.2 Sum Leaf Subordinates

The Sum Leaf Subordinates Quota function sums the leaf subordinates’ quota values and sums them up the
position hierarchy up to the selected position. Based on the leaf subordinates, calculates the quotas for the
managers in the hierarchy.

If you sum subordinates’ values and one of the subordinate’s values is empty, the system omits the null value in
the sum.

Related Information

Quota Functions Overview [page 225]

18.6.3 Distribute to Subordinates

The Distribute to Subordinates Quota function splits the value of the selected position among the position’s
direct subordinates (one level below the selected position).

 Note

Due to rounding, some values might not add up as expected. For example, if you have a value of $0.99 and
you distribute to four subordinates, each subordinate then has a value of $0.25.

Incentive Management Admin Design Guide

226 PUBLIC Quotas Overview
Related Information

Quota Functions Overview [page 225]

18.6.4 Distribute to Leaf Subordinates

The Distribute to Leaf Subordinates Quota function splits the value of the selected position among all of the
position’s subordinates, down to the leaf levels in the hierarchy. The result of this operation is that the sum
of all direct subordinates' values equals the selected position's quota. The quota values for subordinates two
levels down equal the direct subordinates' quota value, and so on down to the leaf levels in the hierarchy.

Related Information

Quota Functions Overview [page 225]

18.6.5 Sum Sub-Periods

The Sum Sub-Periods Quota function sums the quota values for the periods that directly feed into the selected
period value.

For example, if you select a year-based value cell and there are quarter-based quota values that feed into that
annual quota, you can select the year quota value cell and choose the Sum Sub-Periods quota function to
calculate the annual quota based on the quarter values. If there is already a value in the selected cell, the
system replaces the value with a newly calculated value.

Related Information

Quota Functions Overview [page 225]

18.6.6 Distribute to Sub-Periods

The Distribute to Sub-Periods Quota function splits the value of the selected quota in the selected period
among the periods directly within the selected period.

For example, if you select an annual quota value, the system distributes the quota to all four quarters (but not
the months). Also, if you select a quarter value and choose the Distribute to Sub-Periods quota function, the
system distributes the quota values just within that quarter value, not to every month in the year.

Incentive Management Admin Design Guide

Quotas Overview PUBLIC 227
Related Information

Quota Functions Overview [page 225]

18.6.7 Distribute to Leaf Sub-Periods

The Distribute to Leaf Sub-Periods Quota function splits the value of the selected quota in the selected period
among the periods within the selected period, including down to the leaf period value.

Related Information

Quota Functions Overview [page 225]

Incentive Management Admin Design Guide

228 PUBLIC Quotas Overview
19 About Rate Tables

A rate table is a special-purpose table that is used to calculate incentive compensation for a commission,
where a transaction is paid at different rates when it crosses rate threshold tiers. Rate tables can only be used
in incentive rules.

 Note

When using a rate table in a rule and the rate table contains a formula, if the formula uses data that limits
its range of use (such as category or credit data), then you must directly assign the rate table in the rule. In
this case, you cannot use a rate table variable.

Related Articles

• Rate Table Workspace [page 229]

• Creating Rate Tables [page 230]
• Editing Rate Tables [page 232]
• Finding Objects Related to Rate Tables [page 233]

19.1 Rate Table Workspace

Navigate to Compensation Elements > Rate Tables to access the Rate Tables workspace.

The Rate Tables workspace contains two different panels:

• Rate Table Summary

• Rate Table Details (General Information and Associations)

Rate Table Summary

You can create new rate tables, edit existing rate tables, and delete rate tables from the Rate Table Summary
toolbar. You can also view and modify attainment levels from this tab.

Incentive Management Admin Design Guide

About Rate Tables PUBLIC 229
Rate Table Details

You can edit details in the General Information tab. From the Associations tab, you can view the rules that use
the rate table and the elements associated with the rate table.

Related Information

Creating a Rate Table [page 230]

19.2 Creating a Rate Table

When you create a rate table, you provide a name for the Rate Table and select its unit type. Next, you can
specify the layout of the table by defining the rate thresholds and their associated rates.

A rate in a rate table can either be fixed or it can be a formula. You can use a rate table directly in an incentive
rule, or you can use a rate table variable in the rule and then assign the rate table to the variable.

Procedure

1. Choose Compensation Elements > Rate Tables.

2. Choose Create.
3. Select a calendar and specify the Effective Dates for the new rate table from the calendar dialog.
4. Enter a name for the rate table in the Details panel. The name identifies the rate table for selection when
you define the rule elements for a plan assignment. The summary panel immediately reflects your entry. If
your organization has created and implemented business units, you can assign this variable to one or more
business units by selecting from the Business Units drop-down. You can only select business units to which
you as a user have been assigned.
5. (Optional) Enter a description for the rate table.

Incentive Management Admin Design Guide

230 PUBLIC About Rate Tables
6. Select an Input Type for the attainment column.

 Note

If this rate table should be used in step commission calculations, the unit type for both the input type
and return type must be percent. New rules are added to accommodate customer’s needs like Stepped
Commission for non-%% Rate Tables

7. Select a Return Type for the rate column.

8. In the Rate Table area, select operator and enter corresponding Attainment levels. All operator and
attainment level entries, except the last, must be in the format <nn or <=nn, where nn is the attainment
level. The last entry must be in the format >nn or >=nn. The operator for the last entry defaults to ">" or
">=" depending on the operator assigned to the previous tier. If the operator for the previous tier is "< =",
the operator for the last tier defaults to ">". If the operator for the previous tier is "<", the operator for the
last tier defaults to ">". This ensures that there are no gaps between tiers and each tier is appropriately
inclusive or exclusive of the specified attainment value. For the lowest tier this also handles situations in
which attainment falls below the first tier or is negative, such as when sold items are returned or debooked.
9. Enter as many rows as you need to define the attainment levels.

• To add an additional row, position the cursor in a row to make it the active row, and choose the Add icon
from Action. An additional row is inserted before the active row.
• To remove a row, position the cursor in the row and choose the Delete icon.
• To enter the rate for each attainment level, create a formulaic expression, or create a new formula, which
requires that you save the formulaic expression as a new formula.

Related Article

• Creating a Rate Table that Handles Negative Returns [page 231]

19.2.1 Creating a Rate Table that Handles Negative Returns

To use a rate table to handle negative returns, de-bookings, be sure to create your rate tables carefully. For
example, if you have a de-booking and you need to create an incentive that is the exact inverse of the original
incentive, you can create the following rate table:

Attainment Rate

< –150% -20%

< –100% -15

< 100% 10

< 150% 15

>= 150% 20%

Incentive Management Admin Design Guide

About Rate Tables PUBLIC 231
Using this table, a positive 125% falls into the “< 150%” attainment level, whereas a negative 125% (-125%)
falls into the “< (-100%)” attainment level. You can also refer to a fixed value or insert a formula in place of a
rate value.

 Note

When using this same rate table both a positive 25% and a negative 25% (-25%) falls into the same “<
100%” attainment level.

19.3 Editing a Rate Table

Editing a rate table involves any of the following operations:

1. Rename the rate table

2. Add, change, or remove the rate table’s description
3. Change the rate table’s input type or return type
4. Insert or delete an attainment tier

 Note

When you insert a row for an attainment tier using the Insert button, the row is inserted above the
currently selected row. The sytsem attempts to derive the attainment value for the new row based on
the values in the row above it. For example, say you have 3 rows with attainment threshold values of
15%, 20%, and 20% with the operators <=, <= and > respectively. You then select the row with the
value of 20% and the <= operator and insert a row. The system assigns the value of 16% to the new
row based on the 15% value in the row above. However, if you select the row with the value of 16% and
insert a row, the row is inserted, however, because a value between 15% and 16% cannot be derived
the attainment threshold value assigned to the new row is 16% and the value in the original row is
highlighted in blue indicating that it is invalid and must be modified.

5. Change the attainment threshold for an attainment tier

6. Change an attainment tier’s rate
7. Add, change, or remove formulas, variables, or other rule elements in the rate table
8. Change the effective dates of the rate table

 Note

You cannot change the rate table’s calendar. You must instead create a new rate table. Currently, the
association between a calendar and a rate table cannot be broken or changed.

Be aware that when you edit a rate table, you edit the specified version of the rate table. For example, you have
a rate table that is effective from June 2008 to the End Of Time. If, however, in August 2008 you change a rate
in the rate table, it is important to know the effective dates of the change. If, for example, to back-date changes
to June 2008, edit the current version of the rate table (choos Manage Versions in the Rate Tables workspace).
However, to make changes effective from August 2008 to the End Of Time, create a new version of the rate
table, and make the changes to that new version (click New Version in the Rate Tables workspace). If you have a
rate table that is no longer effective, you change the effective end date of the rate table to the required date. Do
not delete the rate table if the rate table was valid for any point in time.

Incentive Management Admin Design Guide

232 PUBLIC About Rate Tables
Related Information

Creating a Rate Table [page 230]

19.4 Deleting a Rate Table

You can delete a rate table that was just created either manually or using import. You cannot delete a rate table
that is referenced by a rule or rule element or is assigned to a rate table variable. Deleting a rate table removes
the rate table object from the system. However, the audit log in the Audit Log workspace retains information on
the actions performed on the rate table object, including its remove (delete) date, and information about the
object itself.

 Note

To delete a particular version of a rate table, use the Manage Versions button on the toolbar.

19.5 Finding Objects Related to Rate Tables

You can find data related to one or more selected rate tables by selecting the appropriate object option from
the Related pane.

Procedure

1. Choose Compensation Elements > Rate Tables.

2. Search for the rate table or rate tables for which to find related data If required.
3. Select the rate table or rate tables from the Summary panel
4. Select an object option from the Related pane, for example, Rules.

• If you’re searching for related plans, the plans are retrieved immediately and the results are displayed in the
Plan workspace. If no results are found, the message “No Records found is displayed.
• If you’re searching for related objects other than plans, the Search for Related Objects dialog displays with
the name of the selected object substituted for the object name.

The available options and data returned are as follows:

• Rules—returns the Rules that are directly referring to the selected rate table.
• Positions—returns the positions that have the rate table in position Variable Assignment.
• Titles—returns the titles that have the selected rate table in the title's variable assignment.
• Referred Formulas—returns the formulas referred by the selected rate table.
• Referring Formulas—returns the formulas referring to the selected rate table.

Incentive Management Admin Design Guide

About Rate Tables PUBLIC 233
• Referring Rate Table—returns the rate tables referring to the selected rate table.
• Referred Rate Table—returns the rate tables referred by the selected Rate Table.
• Referred Fixed Values—returns the fixed values referred to by the selected rate table.
• Referred Variables—returns the variable that is referred to by the selected rate table.
• Referring Variables—returns the variable that has the selected rate table as the default value.
• Referring Lookup Table—returns the lookup tables referring to the selected rate table.
• Referred Lookup Table—returns the lookup tables referred by the selected rate table.
• Quotas—returns the quotas referred to by the selected rate table.
• Plans—returns the following:
• Plans that are referring to the rules that are directly using the selected rate table.
• Plans that have the selected rate table in the plan's variable assignment.

Incentive Management Admin Design Guide

234 PUBLIC About Rate Tables
20 About Lookup Tables

A lookup table is a multidimensional table that you use to store a set of numeric-based values. You can
then refer to the values from rules or formulas. Lookup tables are the same for each plan assignment; they
aren’t customizable for each position assigned to the compensation plan. The values in lookup tables can
be concurrently retrieved by any number of compensation rules or shared formulas. Lookup tables store
indexed values, where each value represents the intersection of multiple criteria and each individual criterion is
specified by an index value.

A lookup table has the following characteristics:

• Can have many dimensions.

• Stores the same type of value in all table cells (for example, a lookup table can’t store both percentages
and currency values in the same table).
• Returns results that don’t depend on what has been already passed through the lookup table—this lookup
behavior is different from the spanning behavior of rate tables.

To use the data stored in a lookup table, you include a reference to the lookup table in a rule, formula, or rule
element. In the reference, you specify the data to pass to the lookup table to determine the cell value to return.

 Note

You can’t copy lookup tables.

Related Articles

• Lookup Tables Workspace [page 237]

• Building a LookupTable [page 240]
• References to Lookup Tables [page 246]
• Editing Lookup Tables [page 248]
• Finding Objects Related to Lookup Tables [page 248]

20.1 About Dimension Types

When you go to view or modify a lookup table, the system displays one entire dimension as the side (vertical)
and another entire dimension as the top (horizontal). When a dimension is a side or top one you can see all
indexes at once.

The following table lists a description for each of the available dimension types.

Lookup Table Dimension Types

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 235
Dimension Type Description Example

Numeric Specific numbers are the dimension’s indexes. A numeric dimension could represent the num-
ber of product lines that are over quota.

String A combination of text and numbers are the dimen- A string dimension could represent event types
sion’s indexes. associated with a transaction.

Note: You can select whether or not String dimen-

sions are case-sensitive.

Numeric Range The dimension’s indexes are represented by A numeric range dimension could represent at-
ranges of numbers. tainment percentages.

 Note
For each dimension of this type, you can spec-
ify whether the low and/or high values are
included in the specified ranges. By default,
both are included.

Category Subcategories or classifiers are the dimension’s A category dimension could represent product
indexes. You can mix and match different levels of types.
subcategories and classifiers as indexes.

 Note
Each dimension can refer to include index val-
ues from only one category hierarchy.

Date Range The dimension’s indexes are represented by A date range dimension could be used to en-
ranges of dates. force a business-wide policy that sales transac-
tions are processed differently according to their
 Note accounting dates.

To specify a date range for a specific cell value,

use a dated list for that cell.

 Note
For each dimension of this type, you can spec-
ify whether the low and/or high values are in-
cluded in the specified ranges. By default, the
system includes both.

Incentive Management Admin Design Guide

236 PUBLIC About Lookup Tables
About Effective Dates in Lookup Tables

Lookup tables and lookup table dimensions and cells comply with the following effective date rules:

• Lookup tables have only one version; however, you can change the effective dates of this version.
• The effective date range of the dimension indexes in a lookup table must be within the date range of the
lookup table.
• The effective date range of cells within a lookup table must be within the date range of the lookup table.

Choose the Calendar field button to the right of the index value to set its effective dates. Indexes that do not
match the lookup table's effective dates have a custom icon. When you open a lookup table to the Values
tab, you can specify the effective date range that the system displays the values for. Cells that have multiple
effective versions display with Various as the cell value. Select a cell to view its effective versions.

If you specify a date range that is outside the effective dates of a dimension index, that index and its values do
not display.

20.2 Lookup Tables Workspace

Navigate to Compensation Elements > Lookup Tables to access the Lookup Tables workspace.

The detail pane of the Lookup Tables workspace contains three tabs: the Lookup Table tab, the Values tab, and
the Associations tab. You can create, modify, and delete lookup tables in this workspace.

Lookup Table Summary

In Lookup Table Summary , you can create new lookup tables, modify existing lookup tables, and delete lookup
tables from the Lookup Table tab.

Lookup Table Details

You can edit details in the General Information tab. From the Values tab, you can specify effective dates for a
lookup table’s dimension index. From the Associations tab, you can view the rules that use the lookup table and
the elements associated with the lookup table.

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 237
20.3 Best Practices for Using Lookup Tables

Here are some best practices when using lookup tables:

• Map out your lookup table beforehand. Before you create your lookup table, map out what your lookup
table should contain and how it should look. For example, use a spreadsheet program to make a grid
representation of the new lookup table. Planning ahead greatly reduces the time it takes to enter your data,
and also helps you to better visualize the lookup table.
• Decide on the number of dimensions before you enter cell values. You should decide on the number of
dimensions before you begin entering cell values. You cannot add dimensions after cell values have been
entered. Adding, modifying, or removing indexes after cell values have been entered is acceptable.
• Decide which dimensions to view as the top and side dimensions. The first dimension that you add
automatically displays as the side dimension, and the second dimension displays as the top dimension.
You can change which dimensions are top, side, or other when viewing a lookup table, but these view
choices are not saved.
• Complexity can affect size and performance. Be aware that a more complex lookup table can potentially
take longer to process. For example, if your lookup table has multiple dimensions, many indexes in each
dimension, and/or many references to constants or shared formulas, your rule processing speed might be
impacted. When the system opens a lookup table, the entire table is opened; therefore, large lookup tables
might take longer to open.
• Consider what parameters you want to pass through the lookup table. When you design your lookup table,
you must consider how it should be implemented and what parameters must be passed to it. For example,
if you build a dimension of the string type, consider what string you are going to specify as the parameter
in the Lookup Table function. Also, you must ensure that the string to be passed to the lookup table is
available in the rule.

Incentive Management Admin Design Guide

238 PUBLIC About Lookup Tables
20.4 Restrictions Involved in Lookup Tables
A lookup table’s range of use is restricted by the combined context of the referring item (the rule or formula)
and the lookup table.

An Indicator of a Lookup Table’s Range of Use

When you open a lookup table, the system displays icons that correlate to the types of rules in which you can
use that lookup table. These icons change depending on the values you specify in the lookup table.

Restrictions Based on a Lookup Table’s Contents or Context

The following general rules apply to how the system restricts the use of lookup tables based on what is included
in the lookup table or where the lookup table is used:

• If a lookup table includes a category type of dimension, that lookup table can be referenced from the
following types of rules only: any credit rules, primary measurement rules, and per-credit commission
incentive rules. This restriction occurs because those are the only rules that have access to classifier
information, either from the transaction or the credit. The same restriction applies if the lookup table is
referenced in a shared formula. The shared formula, in addition to any constraints it itself has, can only be
used in credit rules, primary measurement rules, and per-credit commission incentive rules.
• If a lookup table has a cell value that contains a formula, the lookup table’s range of use is further
constrained by the rule type restrictions of the formula. For example, a lookup table with a category type
dimension references a formula that is available only to direct and indirect credit rules, that lookup table’s
range of use is restricted to only direct and indirect credit rules. If a lookup table includes references to
multiple formulas, the lookup table’s range of use is restricted to the set of rules that can use all of the
referenced formulas.
• If a lookup table references a formula that uses fixed values as input, the lookup table’s range of use is not
further restricted. Formulas that use fixed values as input can be used in any type of rule (as well as rate
tables).
• The lookup table’s return type limits its range of use. The unit type specified as the lookup table’s return
type must match the unit type requested in the referencing rule or formula. For example, if a lookup table
contains data values that are of the percent unit type, a function that calls for a USD value cannot reference
that lookup table.
• The parameters that a formula passes to a lookup table can restrict the formula’s range of use. If a formula
includes a reference to a lookup table, the parameters passed to the lookup table restrict the types of
rules that can use that formula. For example, if a formula references a lookup table that does not include
a category type of dimension, but the formula specifies that the Transaction.GenericAttribute1 field be
passed as one of the lookup table parameters, the formula can only be used in direct credit rules.
• Choose the lookup table dimension type based on its intended usage. Be sure that the unit type for
numeric dimensions is appropriate for the field(s) you are passing as parameters to the lookup table. For
example, if you intend to pass a integer field (such as Transaction.Number of Units) as a parameter to
the lookup table, be sure that the lookup table is integer-based. In this case, a lookup table that uses the
quantity unit type would not accept an integer-based value as a parameter.

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 239
20.5 Options for Cell Values in a Lookup Table

You can specify a value for a cell in a lookup table by specifying one of the following:

• A literal value (directly type it in)

• A fixed value
• A fixed value variable
• A formula
• An effective dated list of values for a cell
• A lookup table
• A lookup table variable
• Nothing (a null value)

Only objects (fixed values, fixed value variables, formulas, and lookup tables) associated with the current
default calendar can be specified. You can switch the kind of value in a cell by simply replacing the current
value; for example, replace a constant reference with a literal value. Dated list values require a little more work
to replace. You can also select multiple cells and edit the value for all at once using the cell value field.

About Literal Values in Lookup Tables

You can directly enter a number to store a literal value. You do not have to specify the unit type symbol (for
example, ”r;$” if the table’s return type is USD). The system displays the appropriate symbol automatically
after you type a number and press Enter. If you try to enter a number and a unit type symbol that differs from
the lookup table’s return type, the system outlines the cell in red to indicate the error (for example, if the lookup
table’s return type is percent and you enter a $). You can also choose to leave a cell value blank (a null value).

About Cell Value Effective Versions in Lookup Tables

You can specify different cell values that are effective for different effective dates. Each version can have a
different cell value.

For example, an organization runs a special promotion for the month of February 2006 for sales transactions
worth more than $10,000 for products sold directly by salespeople in the Bronze performance tier. For the
month of February, the rate is increased by 0.5%. In this example, the effective versions of cell values would
look something like what is shown in the following figure.

20.6 Building a Lookup Table

Before you create your lookup table, map out what your lookup table should contain and how it should look.
For example, use a spreadsheet program to make a grid representation of the new lookup table. Planning ahead
greatly reduces the time it takes to enter your data, and also helps you to better visualize the lookup table.

Incentive Management Admin Design Guide

240 PUBLIC About Lookup Tables
Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Choose Create.
3. Choose an Effective Start and End Date.
4. Choose Ok. This creates a new empty Lookup Table.
5. Specify the following General Information from the Lookup Table Details panel:

Field Description

Name Enter a name for the lookup table.

This is the name that displays in a compensation rule or

shared formula when the lookup table is referenced.

Description (Optional) Enter a description.

Business Units If your organization has created and implemented busi-

ness units, you can assign this rule to a business unit
by selecting from the Business Units drop-down. You can
only select a business unit to which you as a user have
been assigned.

Return Type Select a return type for the lookup table. All cell values in
the lookup table are of this unit type.

Calendar Select the appropriate calendar.

Last Modified This is the date in which this specific record was last modi-
fied

Effective Start Date This is the date in which this specific record becomes
effective

Effective End Date This is the date in which this specific record becomes
inactive

6. At this point, you are ready to create dimensions, their indexes, and the associated values. See Adding a
Dimension to a Lookup Table [page 241]. To ensure that system treats null cell values as zero values, select
the Treat empty values as Zero option. By default, this option is not selected.
7. Choose Save.

20.6.1 Adding a Dimension to a Lookup Table

When viewing a lookup table, the first dimension that you define is, by default, set as the side dimension; the
second dimension that you define becomes the top dimension by default. You can change the top and side
dimensions when viewing a lookup table, but the default settings return when you open the lookup table (in the
Edit Table Cells dialog box).

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 241
You can add a dimension to a lookup table just after you create the table, or you can add a dimension to an
existing lookup table (provided it does not contain any cell values). If a lookup table contains any cell values, the
system does not allow you to add or delete dimensions. The indexes for a particular dimension in a lookup table
are the criteria by which the lookup table function locates an individual cell value.

 Note

Indexes are also effective dated. You can add indexes to a dimension just after you add the dimension, or to
a dimension, you have already created.

Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search and Select a Lookup Table or create a new lookup table from the Summary panel.
3. Choose Add Dimension from Define Dimensions of the details panel.
4. Enter Dimension Name, Type and Input Unit Type. This is the name by which you select the dimension
when viewing it.
5. Choose Finish. You cannot save the dimension without adding at least one index

Dimension Type Parameters

Numeric Enter numbers as indexes.

Specify the input unit type associated with the number

that should be passed to the index values.

String Enter text strings as indexes.

Select the Ignore Case option to specify that lookups on

this dimension are not case-sensitive.

Numeric Range For each index, enter a range of numbers.

Select the Include Low Value and/or Include High Value

options to include the low or high values in each range of
numbers.

Specify the input unit type associated with the number

that should be passed to the index values.

Category After you specify Category as the dimension type, specify

the category hierarchy (root) to use. These are the same
categories listed in the Launch Pad window.

Each index must be from the same category hierarchy, but

the indexes can be any combination of subcategories and
classifiers.

Incentive Management Admin Design Guide

242 PUBLIC About Lookup Tables
 Dimension Type Parameters

Date Range For each index, enter a range of calendar dates.

6. For any dimension type, you can click Sort to sort the indexes in alphanumerical (increasing) order.
However, after you sort the list you cannot re-sort it. If you are specifying a category-based dimension, you
specify the category root in the Dimension Options area.
7. After you have entered the new dimension name, the type, and the category root (if you specified the
category dimension type), you are ready to add the indexes to the dimension. You must have at least one
index in a dimension If you are specifying a numeric range dimension, you specify the Input Unit type. You
can specify to include the Low Value, High Value, or both.
8. In the Dimension Indices area, choose Add to add an index.
• For category dimensions, specify the subcategory or classifier. You can pick from a list, enter part of
the name, or do a search.
• For Date Range or Numeric Range dimensions, the index is a range of values. There are two columns:
one for the low end of the range and one for the high end of the range.
• For Date Range dimensions, you can edit and enter a date, or click the Add button to open the
Dimension Index Effective Dates dialog from which you can select a date.
• The system adds an empty row in the Value column (in the Dimension Indices area).
9. To add more indexes, choose Add, select the new row, and enter the value. Continue until you have added
all the indexes.
10. Choose Save.

20.6.2 Removing a Dimension from a Lookup Table

Removing a dimension causes all cell values to be deleted from the lookup table.

Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table from which you want to remove the dimension.
3. Select the lookup table in the Summary panel
4. Select the dimension from the Dimensions area
5. Choose Delete from Lookup Table.
6. Click Yes to continue, or click No to cancel the remove operation in the Warning dialog. If you clicked Yes,
the sytsem removes the selected dimension from the current lookup table and deletes all cell values from
the lookup table.
7. Click Save.

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 243
20.6.3 Removing an Index from a Lookup Table’s Dimension

An index can be removed whether or not the lookup table has cell values entered. If there are cell values, the
ones that apply to the index are removed along with the index. You can either remove an index or end-date the
version of the index.

Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table from which you want to remove the index.
3. Select the lookup table in the Summary panel
4. Select the index, which is in the Details panel of the Dimension Indices area.
5. Choose Delete. The system removes the selected index and any cells that were associated with the index.
6. Choose Save.

20.6.4 Editing Cells in a Lookup Table

Be sure that all the dimensions are specified for the lookup table before you enter any cell values. After cell
values have been entered in a lookup table, changes to the lookup table’s dimension causes the system to
delete all cell values.

Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table to be modified.
3. Select the lookup table in the Summary panel.
4. Choose the Values tab in the Detail panel.
5. Select the cell to be edited in the lookup table.
6. Edit the value by doing one of the following:
• If the value is a literal, type a new value.
• If the value is a formula or formulaic expression, , choose the Formula button in the selected cell and
enter a formula, formulaic expression, or choose from any legal moves (such as a fixed value variable).
You can select an existing formula or create a new one. To remove a formula and change the value to a
literal instead, you must first delete the formula in the formula editor. To remove a formula and change
the value to a literal instead, you must first delete the formula in the formula editor.
• To edit multiple cell values, in the lookup table, select the cells to be edited using Shift + left-
click . All cells selected must be of the same type, either literals or formulas.

Incentive Management Admin Design Guide

244 PUBLIC About Lookup Tables
7. To create separate effective versions of the cell value, select the cell, and in the lower pane you can create,
edit, and delete effective versions (as you do elsewhere in the product).
8. Choose Save.

 Note

You can have null values in lookup tables (some cells can be empty). You can also choose to specify that
the null values are considered as zero values during calculation processing by selecting the Treat empty
values as Zero option from the Lookup Table tab

20.6.5 Entering a Fixed Value Variable in a Lookup Table Cell

You can include a fixed value variable in a lookup table cell so that you can customize that particular cell’s value
for each position assignment assigned to the associated compensation plan. When you later assign a fixed
value to the variable, you can only assign fixed values that are the same as the lookup table’s return type.

 Note

A quick indicator that a lookup table cell contains either a fixed value, a variable, or a formula reference is
that you see a string value in the cell. Lookup tables can only return numeric-based values.

Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table to be modified.
3. In the Summary pane, select the lookup table.
4. In the detail pane, choose the Values tab.
5. In the lookup table, select the cell to which to add a fixed value variable.
6. Choose the Formula.
7. Create or select a Fixed Value Variable by doing one of the following:
• To create a new fixed value variable, type * in the formula edit pane to display the list of legal moves.
Select Create a New Fixed Value Variable or select Fixed Value Variable from the References list in the
legal moves pane. Type * and select Create a New Fixed Value Variable.
• To select an existing fixed value variable, select Fixed Value Variable from the list of legal moves or
select Fixed Value Variable from the References list. Type the name of the fixed value variable to use
auto-matching, or type * and select the fixed value variable from the list.
8. Choose Save.

20.6.6 Entering Formulas and Expressions in a Lookup Table

Cell
You can either enter a formula or a formulaic expression in a lookup table. The result of the formula or
expression is the cell’s value. When choosing a formula, choose a formula that returns a value with a unit type

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 245
that matches the lookup table’s return type. For example, if a lookup table’s return type is percent, do not
include a formula that returns a value in USD.

Do not use a lookup table to directly refer to another lookup table. Instead, create a formula that refers to
the lookup table, and then use the formula in the other lookup table. The use of a formula instead of a direct
reference to a lookup table from a lookup table cell is required for calculation processing.

Entering an Expression in a Lookup Table Cell

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table to be modified.
3. Select the lookup table in the Summary panel.
4. Choose the Values tab in the Detail panel.
5. Choose the lookup table cell to select it in the cell values area
6. Choose Formula to select items from the list of legal moves to construct your expression.
7. Click Ok to bring the expression over to the lookup table cell.
8. Click Save.

Entering a Formula Reference in a Lookup Table Cell

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table to be modified.
3. Select the lookup table in the Summary panel.
4. Choose Values in the Detail panel.
5. Click the lookup table cell to select it In the cell values area.
6. Choose Formula to select formulas from the list of legal moves.
7. Select formula from the Reference section of the Legal Moves pane.
8. Select an existing formula, by either typing the name of the formula, or typing * and selecting the formula
from the list. Or, create a new formula, by typing * , and then selecting &rdquor; Create a New Formula.
9. Click Ok.

 Note

A quick indicator that a lookup table cell contains either a fixed value, a variable, or a formula reference is
that you see a string value in the cell. Lookup tables can only return numeric-based values.

20.7 Creating a Reference to a Lookup Table

You can use a value from a lookup table in a formula, rule, or another rule element anywhere you can use a
formula or formulaic expression. To access and use data from a lookup table, you include a reference to the

Incentive Management Admin Design Guide

246 PUBLIC About Lookup Tables
lookup table. In the reference, you specify the data to pass to the lookup table, which in turn determines the cell
value that is returned.

Procedure

1. To include a reference to a lookup table, begin from either a compensation rule, formula, or rule element.
From wherever you start, navigate to a New Formula or Edit Formula dialog. In the formula dialog, specify
the return type. The return type corresponds to the unit type of the lookup table’s cell values. For example,
to reference a lookup table that stores USD values, specify the return type as currency.
2. Choose the Formula edit panel to activate legal moves.
3. In the Legal Moves pane, in the References column, double-click Lookup Table or type the first few letters of
the name to select it.
4. In the Formula section, you can do either of the following to specify the lookup table:
• Type * to pick from a list of all lookup tables.
• Type the beginning of the fixed value name to pick from a subset of all lookup tables.
5. Select each parameter in the Formula section, and then either type a literal or select an item from Legal
Moves.
6. Choose Save when you have finished specifying the parameters

20.7.1 Referring to Lookup Tables with Category Dimensions

When referring to a lookup table that has one or more category dimensions, you do not specify an input for
each category dimension. (For other dimension types, you have to specify the field to pass to the lookup table).

The following figure shows a four-dimensional lookup table with two category dimensions.

Instead of passing a field in the reference to the lookup table, the system looks for the classification records
that match category dimension indexes. All classification matches are passed to the lookup table for a possible
match with the lookup table dimension. The more category dimensions there are, the more fields have to
match on the classification record against the lookup table dimensions. The classification records that get
passed are those that are associated with the transactions related to the referring rule or rule element.

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 247
20.8 Editing a Lookup Table

To edit a lookup table involves any of the following operations:

• Rename the lookup table (any rules or shared formulas that refer to the lookup table are updated
automatically)
• Add, change, or remove the lookup table’s description
• Change the type of value stored in the lookup table’s cells (if you do this, the system clears all cell values).
• Change the dimension type of a dimension (if you do this, the system removes all indexes associated with
that dimension)
• Add or remove a lookup table’s dimension.
• Add, rename, replace, or remove indexes within a dimension (renaming a dimension is acceptable, but
adding or removing dimensions causes the system to delete all cell values)

 Note

You cannot edit the structure (return type and number and types of dimensions and their order) of a
Lookup Table that is assigned as the default of a Lookup Table Variable being used in a formula, rule, plan or
another lookup table.

• Edit cell value or bulk edit cell values in a lookup table.

• Add, change, or remove formulas, variables, or other rule elements in the lookup table
• Edit or create new effective versions of dimension indexes, or edit or create new versions of cell values.

 Note

You cannot change the lookup table’s calendar. You must instead create a new lookup table. Currently, the
association between a calendar and a lookup table cannot be broken or changed.

20.9 Deleting a Lookup Table

You can delete a lookup table that was just created either manually or using import. You cannot delete a lookup
table that is referenced by a rule or rule element or is assigned to a lookup table variable.

Deleting a lookup table removes the lookup table object from the the system. However, the audit log in the
Audit Log workspace retains information on the actions performed on the lookup table object, including its
remove (delete) date, and information about the object itself.

20.10 Finding Objects Related to Lookup Tables

You can find data related to one or more selected lookup tables by selecting the appropriate object option from
the Related pane.

Incentive Management Admin Design Guide

248 PUBLIC About Lookup Tables
Procedure

1. Choose Compensation Elements > Lookup Tables.

2. Search for the lookup table or lookup tables for which to find related data.
3. Select the lookup table or lookup tables in the Summary panel
4. Select an object option, for example, Rules in the Related pane

• If you are searching for related plans, the plans are retrieved immediately and the results are displayed in
the Plan workspace. If no results are found, the message No Records Found is displayed.
• If you are searching for related objects other than plans, the Search for Advanced Related Objects dialog
displays with the name of the selected object substituted for the object name.

The available options and data returned are as follows:

• Rules—returns the rules that are directly referring to the selected lookup table.
• Referring Formulas—returns the formulas referring to the selected lookup table.
• Referred Formulas—returns the formulas referred to by the lookup table cells.
• Referred Fixed Values—returns the fixed values referred to by the selected lookup table.
• Referred Variables—returns the variables referred to by the selected lookup table.
• Referring Rate Tables—returns the rate tables referring to the selected lookup table.
• Referred Rate Tables—returns the rate tables referred to by the selected lookup table.
• Quotas—returns the quotas referred to by the selected lookup table.
• Referring Lookup Tale Variables—returns the variables referring to the selected lookup table.
• Referred Lookup Tables—returns the lookup tables referred to by the selected lookup table.
• Referring Lookup Table—returns the lookup tables referring to the selected lookup table.
• Plans—returns all the plans that are referring to the rules that are directly using the selected lookup table.

Incentive Management Admin Design Guide

About Lookup Tables PUBLIC 249
21 About Functions

Functions are predefined formulas provided by the sytsem that you can use in compensation rules to calculate
and specify values or conditions. In general, functions fall into groups based on their use. For example, a group
of functions, called order-level functions, is provided to calculate summary information related to transactions
on an order for use in writing credit rules based on orders. Most functions are accessible from the functions
listing in the Legal Moves pane. A few functions are accessible from the data fields listing in the Legal Moves
pane. These functions are known as data field functions.

The list of functions that are available in the system in a particular context depends on the kind of formula, the
return type of the formula, and the input to the formula. The available functions are listed alphabetically in the
system. Also, new rules are added to accommodate customer’s needs like interpolate functions. In most cases,
functions require one or more input parameters and produce an output result. For example, the Concatenate
Two Strings function takes two strings as input parameters and produces a string as output.

Because of this basic input/output structure, functions can be nested within other functions in a formula. For
example, you can create a formula using the Convert String to Value function, then use that formula as one of
the input parameters to a second formula that includes the Round function.

FormulaA = Convert String to Value

(Participant.GenericAttribute1, "USD")

FormulaB = Round(FormulaA,2)

 Note

When discussing date formats, information in this chapter assumes that you are using the English (United
States) locale. If you are using another locale, date formatting could be different.

Related Articles

• Primary Functions [page 251]

• Sum Functions [page 263]
• Order-Lever Functions [page 273]
• Text Search Functions [page 277]
• Date Functions [page 280]
• Ranking Functions [page 290]
• Proration Functions [page 296]

Incentive Management Admin Design Guide

250 PUBLIC About Functions
21.1 Primary Functions Overview

A primary function is one that is available in most contexts and does not fit into one of the other groupings of
functions. The primary functions are:

• Absolute
• Calculate Result
• Concatenate Two Strings
• Convert Boolean to Value
• Convert Date to Effective Date
• Convert Date to Fiscal Date
• Convert Null to Value
• Convert String to Upper Case
• Convert String to Value
• Convert Value to Boolean
• Current Period
• Equals (Ignore Case)
• Is Null and IsDateNull
• Is In Range
• Max and Min
• Other Position’s Quota or Fixed Value
• Participant.Version() and Position.Version() Functions
• Position Proration Functions
• Power of
• Round
• Set Unit Type
• Source.Credit.Relationship.Source.Version ()
• Transaction.Payee Pre-Assignment () Functions
• Transaction.Classifier()
• Trim String
• Trunc

Related Articles

• Absolute [page 252]

• Calculate Result [page 252]
• Concatenate Two Strings [page 253]
• Convert Boolean to Value [page 253]
• Convert Null to Value [page 253]
• Convert String to Upper Case [page 253]
• Convert String to Value [page 254]

Incentive Management Admin Design Guide

About Functions PUBLIC 251
• Convert Value to Boolean
• Current Period [page 254]
• Equals (Ignore Case) [page 255]
• Is Null and IsDateNull [page 255]
• Is In Range [page 255]
• Max and Min [page 256]
• Other Position’s Quota or Fixed Value [page 256]
• Participant.Version() and Position.Version() Functions [page 257]
• Round [page 257]
• Set Unit Type [page 258]
• Transaction.Payee Pre-Assignment () Functions [page 258]
• Transaction.Classifier() [page 259]
• Trim String [page 262]
• Trunc [page 263]

21.1.1 Absolute

Description: Use Absolute to calculate the absolute positive value of a number.

Input: A numeric value.

Output: A numeric value.

Formula: Absolute = Value (Transaction.Value)

For example, if the input value is $130.00, the output value is $130.00; if the input value is –$25.00, the output
value is $25.00.

21.1.2 Calculate Result

Use Calculate Result to extract a value from a rate table; the function returns a single value per input value.
This function looks up a value on a rate table without traversing rate rows (this is unlike stepping through a
rate table, where the value is derived from traversing rows). A rate table used solely for a Calculate Result
function can use any unit type for the lookup and the result columns - (USD in, quantity out) for example. A
step commission rate table can only use the same unit type (percent in, percent out). If you want to have more
than two dimensions, use a lookup table instead.

Input:

• Rate Table - Specify either a rate table or a rate table variable. If you specify a rate table variable, it acts as a
placeholder, and the actual rate table must be assigned at the variable, plan, title, or position level.
• Attainment Rate - Enter or select the value that determines which row of the rate table to use, based on
the second column (attainment) in the rate table. The attainment rate is normally specified by selecting
a Measurement but can be specified by selecting a Fixed Value, a Fixed Value Variable, a Formula, an
Incentive, a Lookup Table, a Lookup Table Variable, or a Quota.

Incentive Management Admin Design Guide

252 PUBLIC About Functions
Output: The value according to the third column is returned.

Formula: Calculate Result = (Rate Table (BookedRev_RT)), (Attainment (AP Simple Revenue PM:month))

For example, if a participant achieves 104% of attainment, and using rate table with the following attainment
tiers and rates (0 - 100% = $3000; 100%+ = $5000), Calculate Result would return a value of $5000.

21.1.3 Concatenate Two Strings

Use the Concatenate Two Strings function if you want to use the combination of two strings in a formula.

Input: Two strings.

Output: One string (String return type)

Formula: Concatenate Two Strings (Participant.ID, Position.GA1_Region)

21.1.4 Convert Boolean to Value

Description: Converts a Boolean value to a numeric value.

Input: A Boolean value.

Output: A numeric value (Percent, Integer, or Quantity return type)

Formula: Convert Boolean to Value(true) = 1

21.1.5 Convert Null to Value

Description: Converts a null value to a numeric value.

Input: Two numeric values: First Value and Second Value. If the First Value parameter is not null, this value is
returned as output. However, if the First Value parameter is null, the Second Value parameter is returned as
output.

Output: Either the value specified for the First Value or the Second Value as explained above.

Formula: Convert Null to Value (Position.GenericNumber1,0)

For example, the formula example uses Position.GenericNumber1 if it is not null, or 0 if it is null.

21.1.6 Convert String to Upper Case

Description: Use Convert String to Upper Case if you want to convert a text string to all capital letters. For
example, you could use this function in a classification rule to ensure that a transaction field matches a
classifier field.

Incentive Management Admin Design Guide

About Functions PUBLIC 253
Input: A string field.

Output: The same string, in all capital letters (String return type)

Formula: Convert String to Upper Case("market")=”MARKET”

For example, the example converts market to MARKET.

21.1.7 Convert String to Value

Description: Use Convert String to Value to extract a numeric string from an alphanumeric field (often from a
generic attribute) in the database, then apply a unit type to the string so it has the correct format for use with
other mathematical elements. This makes the string a “number” in a sense that the sytsem can interpret it.

Input:

• Numeric string—The string to be converted

• Unit Type—The type of value to create.

Output: A numeric value with the specified unit type.

Formula: Convert String to Value = (string (Participant.Generic Attribute 1), Unit type (USD))

For Example, Extract the numeric string in a participant first generic attribute field (that stores a conversion
rate, for example) and specify a unit type of USD.

 Note

When specifying a percent-based unit type, the percentage is based on the created value. A value of 0.1
becomes 10%, and a value of 1.0 becomes 100%.

21.1.8 Convert Value to Boolean

Description: Converts a numerical value to a Boolean value.

Input: A numeric value.

Output: A Boolean value (true or false).

Formula: Convert Value to Boolean(Transaction.Generic Number1)=true

For example, If Transaction.Generic Number1 equals 1, the numeric value is converted to Boolean.

21.1.9 Current Period

Description: Use Current Period to ensure that a rule is only fired in the appropriate period.

Input: A period from the list of all periods in current default calendar.

Output: A Boolean value (true or false)

Incentive Management Admin Design Guide

254 PUBLIC About Functions
For example, If you write rules that create Quarterly or Yearly or higher level incentives (any non-leaf level
persistent Incentive), you would use Current Period in the condition to make sure the rule only fires in a valid
period. For example, a year incentive should have the condition “Current Period = December 1999?. A quarter
incentive would include the following:

Current Period = March Or

Current Period = June Or

Current Period = September Or

Current Period = December

21.1.10 Equals (Ignore Case)

Description: Use this function to make two items with different capitalization considered as the same for rule
processing purposes. Enter two strings are considered equal.

Input:

• First String—The character string used for comparison.

• Second String—The character string that the first string is compared against.

Output: A Boolean value (true or false).

Formula: Equals Ignore Case = (First String (Position.Name), Second String (“Sales rep”))

For example, You might want to ensure that commissions involving sales representatives receive the
appropriate amounts from measurements labeled either 'Sales Rep' or 'Sales rep.'

21.1.11 Is Null and IsDateNull

Description: Use the Is Null function to test if a field is null (does not contain a value). Use the Is Date Null
function to test if a date field is null.

Input: Specify the field that is to be tested for a null. If the field is null, the function returns a “true,” otherwise
the function returns a “false.”

Output: A Boolean value (true or false).

Formula: isNull (Transaction.Generic Attribute 1)

For example, check to verify that the first generic attribute field on the transaction contains a value.

21.1.12 Is In Range

Description: Determines if a specified numerical value is within a defined range.

Incentive Management Admin Design Guide

About Functions PUBLIC 255
Input: This function takes the following parameters:

• Input value (a numerical value)

• Low value
• Is range inclusive of low value
• High value
• Is range inclusive of high value

Output: A Boolean value (true or false)

For example, If the range is 5 to 10, an input value of 7 returns true. An input value of 5 is in the range if the first
Boolean (Is range inclusive of low value) is true; otherwise, it is not in the range. An input value of 10 is in the
range if the second Boolean (Is range inclusive of high value) is true; otherwise, it is not in the range.

21.1.13 Max and Min

Description: Use these two functions to select the maximum or minimum of two values.

Input: Enter or select the two values that you want compared to determine which is the greater or lesser value.

Output: In the formula, the one that satisfies either maximum or minimum, whichever is selected, is used.

Formula: Max = First value (Source Credit.Transaction.Num Units), Second value (Fixed Value
Variable:MaxNumberOfUnitsOnTxn)

For Example, compare the number of units sold on a transaction to the maximum number of units a sales
representative can receive credit for.

21.1.14 Other Position’s Quota or Fixed Value

Description: Use this function to retrieve a quota or other fixed value from another position. You use a fixed
value variable as a placeholder for the fixed value. The system locates the fixed value that you assign to the
variable (at the position, title, plan, or variable level) along the roll relationship of the specified roll type. You can
use this function anywhere a fixed value or fixed value variable is valid.

Input: This function takes the following parameters:

• Quota or Fixed Value Variable

• Roll Type
• Type of Operation—The options are Average, Sum, or Error, which indicates the type of mathematical
operation to perform. You can specify to take the average, if there is more than one fixed value, sum the
values, or produce an error if there is more than one fixed value.

Output: An amount, with a unit type of the fixed value.

For example, Other Position’s Quota or Fixed Value = Quota or Fixed Value Variable (Fixed Value (Rolling
Monthly Quota:month)), Roll Type (Rollup), Operation is one of Average, Sum, or Error (Error if more than one))

Incentive Management Admin Design Guide

256 PUBLIC About Functions
21.1.15 Participant.Version() and Position.Version() Functions

Description: Use the Participant.Version() or Position.Version () data field functions to return an attribute on a
specific version of a participant or position.

Input: A date, which determines the version of the participant or position to be used. This date can only be a
literal, such as 01/01/08, or a date data field attribute, such as Participant.Hired or Participant.Generic Date 1.

Output: The attribute specified for the participant or position. For example, if you specify Manager.Name,
using Position.Version(Participant.Hired). Manager.Name, the manager’s name, a string, is returned. The type
of output depends on the attribute specified and the return type of the formula or rule.

For example, you could use the Position.Version() function to retrieve the version of the position that is in effect
on the transaction’s accounting date, and then use that position version’s target compensation in a formula for
calculation. You might do this if the position’s target compensation changed during the quarter.

21.1.16 Round

Description: Use the Round function to round a number to a specified number of digits using standard
rounding or bankers rounding.

Standard Rounding (Round Half Up) is the default in Incentive Management. Standard Rounding is a rounding
mode that rounds towards the 'nearest neighbor' unless both neighbors are equidistant, in which case it rounds
up.

For example:

• 0.25 goes to 0.3

• 0.24 goes to 0.2

Banker’s Rounding (Round Half Even) is a rounding mode that rounds towards the 'nearest neighbor' unless
both neighbors are equidistant, in which case it rounds towards the even neighbor. It behaves like round up if
the digit to the left of the discarded fraction is odd and like round down if it is even. Note that this rounding
mode minimizes cumulative error when applied repeatedly over a sequence of calculations.

For example:

• 0.25 goes to 0.2

• 0.35 goes to 0.4

 Note

You must create a support ticket to enable the bankers rounding mode in your tenant.

Input:

• Value—The number to be rounded.

• Number of digits—The number of digits entry specifies where the rounding occurs. Positive numbers and
zero affect the right side of the decimal point, indicating how many decimal places to keep after the
rounding, and negative numbers affect the left side of the decimal point, indicating which places to the left
to round up or down.

Output: A rounded number.

Incentive Management Admin Design Guide

About Functions PUBLIC 257
Formula: Round = (Value (Transaction.Unit Value)), (Number of digits (2))

For example, If the value being rounded is 135.79, the following table shows the different possible results
depending on the precision level specified (number of digits to round to).

Rounding Examples

Scale (Number of Digits) Action Result

1 Round to the nearest tenth 135.8

0 Round to the nearest 1 136

-1 Round to the nearest 10 140

-2 Round to the nearest 100 100

Values displayed as percentages are stored as decimal values, so that 96.78% is stored as 0.9678. When
rounding a percentage, select the number of digits relative to the decimal expression of the percentage. For
example, to round 96.78% (.9678) to 97% (.97), enter 2 for number of digits.

21.1.17 Set Unit Type

Description: Use the Set Unit Type function to assign a unit type to a value. For example, if you want to assign a
currency to a credit value, use this function.

Input:

• Value—A numeric value.

• Unit Type—A unit type for the specified value.

Output: A value with a unit type.

For example, Set Unit Type( $100, euro)

21.1.18 Transaction.Payee Pre-Assignment () Functions

Description: You can use the following data field functions to retrieve pre-assigned transactions based on the
position’s, title’s, or participant's generic attributes information that displays on the pre-assigned transaction.

• Transaction.Transaction Payee Pre-Assignment For Participant ()

• Transaction.Transaction Payee Pre-Assignment For Position ()
• Transaction.Transaction Payee Pre-Assignment For Title ()

Input: None

Return Type: Numeric, Integer, Boolean, or String. The return type depends on the type of generic attribute
being retrieved.

For example, Transactions could be assigned such that the first set of payees specified on a transaction
receive 65% of the credit for the transaction, and anyone specified in the second set of payees on the

Incentive Management Admin Design Guide

258 PUBLIC About Functions
transaction receive 35% of the credit. Then, in your credit rules, you could build a condition that uses one of the
transaction pre-assignment index functions to return a generic attribute such as Transaction.Transaction Payee
Pre-Assignment For Participant().Generic Attribute 1.

 Note

Be careful to avoid ambiguous Transaction Pre-assignment Generic Attribute references. For example,
if a given transaction has two pre-assignment records for a payee that exists in two positions and
the same Generic Attribute on the two pre-assignment records is given distinct values, referencing
Transaction.Transaction Payee Pre-Assignment for Participant is an ambiguous reference, because the
same payee (Participant) exists on both of the transactions pre-assignment records. The correct reference,
in this case, should be Transaction.Transaction Payee Pre-Assignment for Position; because the Position
reference yields a distinct answer. The GA referenced for this transaction is distinct only in relation to
position, not to payee. Similarly, if the same title or position is referenced (but the payee varies) on multiple
assignments for the same transaction, the appropriate function to use would be payee-based reference.

21.1.19 Transaction.Classifier()
Description: Use this data field function to retrieve data on the classifier against which a transaction was
classified.

Input: Specify a category hierarchy in which to find the classifier.

Return Type: Depends on the return type of the selected classifier field.

Transaction.Classifier With Matching GA(): Enables you to use an additional Generic Attribute in the
Classifier.

Transaction.Classifier With Two Matching GA(): Enables you to use two Generic Attributes in the Classifier.

For example, As part of a condition to a credit rule, you could use a formula that compares the classifier’s cost
to a specified amount.

 Note

If a single transaction classifies more than once under a given category hierarchy (classifies against 2 or
more distinct classifiers under the same tree); the use of the Transaction.Classifier() function to return
attributes from a classifier can return ambiguous results. The calculation will use the first classification
record to determine which classifier it returns attributes for. That may or may not be the desired classifier
reference. In this case, you can use the data field function "Transaction.Classifier With Matching GA" or
"Transaction.Classifier With Two Matching GA" which allows you to use additional Generic Attribute in the
Classifier to resolve the ambiguity. (Note that this can only happen when this rule is violated when building
classification rules - "If you have several category hierarchies with the same classifier type, the same
transaction can be classified under each category hierarchy, but not twice under the same one").

Transaction.Classifier With Matching GA

The data field function Transaction.Classifier With Matching GA works similar to the Transaction.Classifier
( Category Tree ) function, except it also takes two parameters, "GA Index" and "Value". The "GA Index"

Incentive Management Admin Design Guide

About Functions PUBLIC 259
parameter specifies which Generic Attribute field in the classifier is used to match against the value specified in
the "Value" parameter. The valid value for the “GA Index” is 0 to 16, with a value of 0 for classifier name and 1
for Generic Attribute1 and a value of 2 for Generic Attribute2 etc. Any value specified that is outside this range
will be ignored. The value for the “Value” parameter can be a literal value or a data field.

The signature of the function is as follows:

Transaction.Classifier With Matching GA ( Category Tree, GA Index, Value )

Category Tree - Category Tree the Classifier is associated

GA Index - GenericAttribute field in the Classifier used to match the Value

Value - Matching Value for GA Index

Example

If the above function returns multiple classifiers, it will compare the value in the classifier's GenericAttribute1 to
see if it matches the Participant's participantID. If it is a match, it will use this classifier. If it doesn't match, it will
try the next one. If there is no match, it will return any classifier.

Transaction.Classifier With Two Matching General Attributes (GA)

The data field function Transaction.Classifier With Two Matching GA will take two more parameters to specify
additional fields in the Classifier to match with the value. This data field function will return all classifiers
classified against the Transaction with the value in the Classifier's GA field matching the value for the first and
second GA index.

The signature of the function is as follows:

Transaction.Classifier With Two Matching GA ( Category Tree, GA Index 1, Value 1, GA Index 2, Value 2 )

Category Tree - Category Tree the Classifier is associated

GA Index 1 - GenericAttribute field in the Classifier used to match the Value

Value 1 - Matching Value for GA Index 1

GA Index 2 - Additional GenericAttribute field in the Classifier used to match the Value

Value 2 - Matching Value for GA Index 2

Incentive Management Admin Design Guide

260 PUBLIC About Functions
Example

The above function will return the Classifier that is classified against the current transaction and the
Classifier's GenericAttribute1 that has a value that matches the current Position's name and the Classifier's
GenericAttribute2 that has a value that matches the current transaction's GenericAttribute1 value.

 Note

For Classifiers to be returned, both GA values must match the matching value. If the Classifier's GA field or
the matching value is null (i.e., unspecified), the system will consider it as ‘not matching’.

Use Case

Transaction.Classifier With Two Matching GA ( Product, 1, Position.name, 2, Transaction.GenericAttribute1 )

First, Classifier has to be classified to the Transaction to be considered. Then, for all the classified transactions,
only the one that has both the GA1 and GA2 values match the matching value will be considered a match. Any
null value will be considered as Unknown so it will not be match.

The following table gives an example of what is considered a match:

Incentive Management Admin Design Guide

About Functions PUBLIC 261
21.1.20 Position.Has Accepted Form

Description: Use this data field function to check if the current processing position has any accepted plan
document. Plan document is accepted if it is accepted by a Payee and has not been undistributed.

Input: Specify the Form Template Name. It is the name of the distribution created for the documents.

Return Type: A Boolean value (true or false).

The data field function Position.Has Accepted Form is a boolean function that returns true if the current
processing Position has an Accepted document. After a document is created in in Plan Communicator, it is
distributed to Payees for acceptance, as part of the distribution process. Documents can also be undistributed
(that is. withdrawn or recalled) if the user decides to stop the distribution process.

Documents that are undistributed cannot be accepted.

This function only checks for the last status of the distribution process to determine whether it is accepted.

If you have a document that was accepted and later undistributed, it will not be considered as accepted. For
details of the distribution process, see Distributions in Plan Communicator.

Example

The below example shows a formula that checks if the Position has accepted the document in the My
Distribution workflow.

21.1.21 Trim String

Description: Use the Trim String function to trim extra white spaces from a text field’s value. For example, you
could use the Trim String function to retrieve just the text string from a transaction field. Imported transactions
often have extra white spaces, which can sometimes cause problems in calculation processing.

Input: A string.

Output: A string, leading or trailing white spaces removed.

Incentive Management Admin Design Guide

262 PUBLIC About Functions
21.1.22 Trunc

Description: Use this function to truncate a number to a specified number of digits.

Input: A number to be truncated, and the number of digits (scale) where truncation occurs.

• Positive numbers and zero affect the right side of the decimal point, indicating how many decimal places to
keep.
• Negative numbers affect the left side of the decimal point, indicating which places to the left to truncate
(that is, change to zero).
• Values displayed as percentages are stored as decimal values, so that 96.78% is 0.9678. When truncating
a percentage, select the number of digits relative to the decimal expression of the percentage. For example,
to truncate 96.78% (.9678) to 96.7% (.967), enter 3 for number of digits.

For example, the number 135.7654, would be truncated as shown in the following table.

Truncation Examples

Scale Action Result

1 Truncate at the tenth position 135.7654 becomes 135.7

0 Truncate at the ones position 135.7654 becomes 135

-1 Truncate at the 10s position 135.7654 becomes 130

-2 Truncate at the 100s position 135.7654 becomes 100

Output: A truncated number. (Return type currency, integer, percent, or quantity).

For example, Truncate the monthly exchange rate to two places to the right of the decimal point (scale of 2).
The monthly exchange rates are imported as fixed values with a scale of 4, and company policy is to truncate,
rather than round, all exchange rates.

Formula: Trunc = Value (Monthly Quota:month), Scale (2)

21.2 Sum Functions Overview

This section includes information about the functions that can do sum operations on various results data.

• Sum Prior Quotas or Fixed Values

• Sum Prior Measurements
• Sum Prior Incentives
• Sum Quotas or Fixed Values to Date
• Sum Measurements to Date
• Sum Incentives to Date
• Sum Deposits to Date and Sum Deposits to Date with Status

Incentive Management Admin Design Guide

About Functions PUBLIC 263
Related Articles

• Sum Prior Quotas or Fixed Values [page 264]

• Sum Prior Measurements [page 264]
• Sum Measurements to Date by Participant [page 265]
• Sum Prior Measurements by Participant [page 266]
• Sum Prior Incentives [page 267]
• Sum Incentives to Date by Participant [page 268]
• Sum Quotas or Fixed Values to Date [page 270]
• Sum Measurements to Date [page 271]
• Sum Incentives to Date [page 271]
• Sum Deposits to Date and Sum Deposits to Date with Status [page 272]

21.2.1 Sum Prior Quotas or Fixed Values

Description: Use this function to obtain a quota or fixed value that crosses the boundaries of the usual
calendar periods. For example, you can sum the values of a rolling quarter period of the last three months, even
when those months do not constitute a calendar quarter.

Inputs to Sum Prior Quotas or Fixed Values Function

Input Description

Quota or Fixed Value Specify a quota, fixed value, or fixed value variable.

Number of periodic values to include Indicates how many prior periods (not including the current period) to
include in the sum, enter the number.

Use true to include the current period Indicates whether or not to include the current period in the sum,
select True or False.

Output: The sum of prior values, as appropriate.

Example: A participant gets compensated based on the last three months’ performance compared to the
quarterly quota.

Formula: Sum Prior Quotas or Fixed Values = (Quota or Fixed Value (Last Value (MonthlyQuota:month)), (Num
Value (2)), (Include Last? (true))

21.2.2 Sum Prior Measurements

Description: Use this function to obtain a measurement value that crosses the boundaries of the usual
calendar periods. For example, you can sum the values of a rolling quarter period of the last three months, even
when those months do not constitute a calendar quarter.

Incentive Management Admin Design Guide

264 PUBLIC About Functions
Inputs to Sum Prior Measurements Function

Input Description

Measurement Select the first parameter, and in the Legal Moves area, under the References column,
double-click the Measurement Input item to open the Measurement Input Reference
dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not
specify a synthetic version of a measurement in a sum function.

Number of Measurements to in- Indicates how many prior periods (not including the current period) to include in the
clude sum; enter the number.

Include Last Measurement in Indicates whether or not to include the current period in the sum; select True or False.
Calculation?

Output: The sum of prior measurements as appropriate.

Example: An incentive rule pays out if the last six months’ performance is above a specified number. The
formula calculates the last six months’ worth of the Sales Revenue PM (primary measurement).

Formula: Sum Prior Measurements (Measurement (Sales Revenue PM: month), Num Measurements (6),
Include Last? (false))

 Note

Traces (which include Incentive to Measurement trace, Measurement to Measurement trace and Deposit
to Measurement trace) will not be created for any Sum Measurement function. Only direct reference to the
Measurement will have traces created.

21.2.3 Sum Measurements to Date by Participant

Description: Use this function to obtain measurement values to determine performance progress so far during
a period. The value shows accumulation toward a goal that you can compare (usually through a condition) to
something else to determine attainment. The details indicate which value and how much of it to sum.

 Note

Because measurements are always calculated at the leaf-period (for example, monthly), you can point to
any period-based version of a measurement.

Input for Sum Measurements to Date by Participant function

Incentive Management Admin Design Guide

About Functions PUBLIC 265
Input Description

Measurement Select the first parameter, and in the Legal Moves area, under the References column, double-
click the Measurement Input item to open the Measurement Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not specify
a synthetic version of a measurement in a sum function.

Period Type The period in which to sum the measurement (for example, ”r;year” to date).

Include Last Measurement Indicate whether or not to include the current subset of that period in the sum; select True or
in Calculation? False. For example, you could use this function to total a monthly value, quarter to date, with
(True) or without (False) the current month.

Output: A calculated measurement value.

Example: If a participant has achieved more than 75% of the annual quota, then award the participant a bonus.
The formula calculates the attainment year to date (so far).

Formula: Sum Measurements to Date by Participant = (Measurement (Manager Revenue PM: month), Period
Type (year), (Include Last? (true))

 Note

To see the difference between Sum Measurements to Date by Participant function and the existing Sum
Measurements to Date function, assign the same participant (payee) to different Position for a different
period and then use the Sum Measurements to Date function to sum over the periods. The new Sum
Measurements to Date by Participant function gives the sum for the same participant whereas the regular
Sum Measurements to Date function gives the sum for the same position.

 Note

Traces (which include Incentive to Measurement trace, Measurement to Measurement trace and Deposit
to Measurement trace) will not be created for any Sum Measurement function. Only direct reference to the
Measurement will have traces created.

21.2.4 Sum Prior Measurements by Participant

Description: Use this function to obtain a measurement value that crosses the boundaries of the usual
calendar periods. For example, you can sum the values of a rolling quarter period of the last three months, even
when those months do not constitute a calendar quarter.

Inputs to Sum Prior Measurements by Participant Function

Incentive Management Admin Design Guide

266 PUBLIC About Functions
Input Description

Measurement Select the first parameter, and in the Legal Moves area, under the References column,
double-click the Measurement Input item to open the Measurement Input Reference
dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not
specify a synthetic version of a measurement in a sum function.

Number of Measurements to in- Indicates how many prior periods (not including the current period) to include in the
clude sum; enter the number.

Include Last Measurement in Indicates whether or not to include the current period in the sum; select True or False.
Calculation?

Output: The sum of prior measurements by the participant as appropriate.

Example: An incentive rule pays out if the last six months’ performance is above a specified number. The
formula calculates the last six months’ worth of the Sales Revenue PM (primary measurement).

Formula: Sum Prior Measurements by Participant (Measurement (Sales Revenue PM: month), Num
Measurements (6), Include Last? (false))

 Note

To see the difference between Sum Prior Measurements by Participant function and the existing Sum
Prior Measurements function, assign the same participant (payee) to different Position for a different
period and then use the Sum Prior Measurements function to sum over the periods. The new Sum Prior
Measurements by Participant function gives the sum for the same participant whereas the regular Sum
Prior Measurements function gives the sum for the same position.

 Note

Traces (which include Incentive to Measurement trace, Measurement to Measurement trace and Deposit
to Measurement trace) will not be created for any Sum Measurement function. Only direct reference to the
Measurement will have traces created.

21.2.5 Sum Prior Incentives

Description: Use this function to obtain an incentive value that crosses the boundaries of the usual calendar
periods. For example, you can sum the incentive values of a rolling quarter period of the last three months, even
when those months do not constitute a calendar quarter.

Inputs to Sum Prior Incentives Function

Incentive Management Admin Design Guide

About Functions PUBLIC 267
Input Description

Incentive Select the first parameter, and in the Legal Moves area, under the References column,
double-click the Incentive Input item to open the Incentive Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not
specify a synthetic version of an incentive in a sum function.

Number of Incentives to In- Indicates how many prior periods (not including the current period) to include in the sum,
clude enter the number.

Include Last Incentive in Cal- Indicates whether or not to include the current period in the sum, select True or False.
culation?

Output: The sum of prior incentives, as appropriate.

Formula: Sum Prior Incentives ((Incentive (Director Revenue Commission: month)), (Num Incentives (6)),
(Include Last? (false)))

 Note

Traces (which include Incentive to Incentive trace and Deposit to Incentive trace) will not be created for any
Sum Incentive function. Only direct reference to the Incentive will have traces created.

21.2.6 Sum Incentives to Date by Participant

Description: Use this function to obtain incentive values to use to determine performance progress so far
during a period. The details indicate which value and how much of it to sum.

 Note

Last Incentive cannot refer to an incentive period lower than the period level of the incentive. For example,
if the incentive is a quarterly bonus, you cannot refer to the monthly value of the incentive. You can refer to
the quarterly or yearly values.

Input for Sum Incentives to Date by Participant function

Input Description

Incentive Select the first parameter, and in the Legal Moves area, under the References column, double-
click the Incentive Input item to open the Incentive Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not specify
a synthetic version of an incentive in a sum function.

Period Type The period in which to sum the incentive (for example, ”r;year” to date).

Incentive Management Admin Design Guide

268 PUBLIC About Functions
Input Description

Include Last Incentive in Indicate whether or not to include the current subset of that period in the sum select True or
Calculation? False. For example, you could use this function to total a monthly value, quarter to date, with
(True) or without (False) the current month.

Output: A calculated incentive value.

Example: Calculate the incentives year to date less the amount paid so far. The formula calculates the
incentives year to date.

Formula: Sum Incentives To Date by Participant = (Incentive (Director Revenue Commission:month), Period
Type (year), Include Last? (true))

 Note

To see the difference between Sum Incentives to Date by Participant function and the existing Sum
Incentives to Date function, assign the same participant (payee) to different Position for a different period
and then use the Sum Incentives to Date function to sum over the periods. The new Sum Incentives to Date
by Participant function gives the sum for the same participant whereas the regular Sum Incentives to Date
function gives the sum for the same position.

 Note

Traces (which include Incentive to Incentive trace and Deposit to Incentive trace) will not be created for any
Sum Incentive function. Only direct reference to the Incentive will have traces created.

21.2.7 Sum Prior Incentives by Participant

Description: Use this function to obtain an incentive value that crosses the boundaries of the usual calendar
periods. For example, you can sum the incentive values of a rolling quarter period of the last three months, even
when those months do not constitute a calendar quarter.

Inputs to Sum Prior Incentives by Participant Function

Input Description

Incentive Select the first parameter, and in the Legal Moves area, under the References column,
double-click the Incentive Input item to open the Incentive Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not
specify a synthetic version of an incentive in a sum function.

Number of Incentives to In- Indicates how many prior periods (not including the current period) to include in the sum,
clude enter the number.

Include Last Incentive in Cal- Indicates whether or not to include the current period in the sum, select True or False.
culation?

Incentive Management Admin Design Guide

About Functions PUBLIC 269
Output: The sum of prior incentives by a participant, as appropriate.

Formula: Sum Prior Incentives by Participant ((Incentive (Director Revenue Commission: month)), (Num
Incentives (6)), (Include Last? (false)))

 Note

To see the difference between Sum Prior Incentives by Participant function and the existing Sum Prior
Incentives function, assign the same participant (payee) to different Position for a different period and then
use the Sum Prior Incentives function to sum over the periods. The new Sum Prior Incentives by Participant
function gives the sum for the same participant whereas the regular Sum Prior Incentives function gives
the sum for the same position.

 Note

Traces (which include Incentive to Incentive trace and Deposit to Incentive trace) will not be created for any
Sum Incentive function. Only direct reference to the Incentive will have traces created.

21.2.8 Sum Quotas or Fixed Values to Date

Description: Use this function to obtain quotas or fixed values to determine performance progress so far
during a period. The details indicate which value and how much of it to sum.

 Note

The Period Type must refer to the same or a larger period at which the quota or fixed value is stored.
For example, if “Sales Quota 2008? is stored as quarterly values only, you should not refer to the monthly
values of that fixed value, but you can refer to a quarter or year period.

Input for Sum Values to Date function

Input Description

Quota or Fixed Value Specify a quota, a fixed value, or fixed value variable.

Period Type The period in which to sum the value (for example, “year? to date). This
should match or contain the period type of the quota, fixed value or
fixed value variable.

Use true to include the current period Indicate whether or not to include the current subset of that period in
the sum; select True or False. For example, you could use this function
to total a quarterly value, quarter to date, with (True) or without (False)
the current month.

Output: A calculated value.

Formula: Sum Quotas or Fixed Values to Date = (Quota or Fixed Value (AP Simple Commission Incentive:
month)), Period Type (month), Include Last? (true))

Incentive Management Admin Design Guide

270 PUBLIC About Functions
21.2.9 Sum Measurements to Date

Description: Use this function to obtain measurement values to determine performance progress so far during
a period. The value shows accumulation toward a goal that you can compare (usually through a condition) to
something else to determine attainment. The details indicate which value and how much of it to sum.

 Note

Because measurements are always calculated at the leaf-period (for example, monthly), you can point to
any period-based version of a measurement.

Input for Sum Measurements to Date function

Input Description

Measurement Select the first parameter, and in the Legal Moves area, under the References column, double-
click the Measurement Input item to open the Measurement Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not specify
a synthetic version of a measurement in a sum function.

Period Type The period in which to sum the measurement (for example, “year? to date).

Include Last Measurement Indicate whether or not to include the current subset of that period in the sum; select True or
in Calculation? False. For example, you could use this function to total a monthly value, quarter to date, with
(True) or without (False) the current month.

Output: A calculated measurement value.

Example: If a participant has achieved more than 75% of the annual quota, then award the participant a bonus.
The formula calculates the attainment year to date (so far).

Formula: Sum Measurements to Date = (Measurement (Manager Revenue PM: month), Period Type (year),
(Include Last? (true))

 Note

Traces (which include Incentive to Measurement trace, Measurement to Measurement trace and Deposit
to Measurement trace) will not be created for any Sum Measurement function. Only direct reference to the
Measurement will have traces created.

21.2.10 Sum Incentives to Date

Description: Use this function to obtain incentive values to use to determine performance progress so far
during a period. The details indicate which value and how much of it to sum.

Incentive Management Admin Design Guide

About Functions PUBLIC 271
  Note

Last Incentive cannot refer to an incentive period lower than the period level of the incentive. For example,
if the incentive is a quarterly bonus, you cannot refer to the monthly value of the incentive. You can refer to
the quarterly or yearly values.

Input for Sum Incentives to Date function

Input Description

Incentive Select the first parameter, and in the Legal Moves area, under the References column, double-
click the Incentive Input item to open the Incentive Input Reference dialog:

Note: It is recommended that you not specify an offset for sum functions. Also, do not specify
a synthetic version of an incentive in a sum function.

Period Type The period in which to sum the incentive (for example, “year? to date).

Include Last Incentive in Indicate whether or not to include the current subset of that period in the sum select True or
Calculation? False. For example, you could use this function to total a monthly value, quarter to date, with
(True) or without (False) the current month.

Output: A calculated incentive value.

Example: Calculate the incentives year to date less the amount paid so far. The formula calculates the
incentives year to date.

Formula: Sum Incentives To Date= (Incentive (Director Revenue Commission:month), Period Type (year),
Include Last? (true))

 Note

Traces (which include Incentive to Incentive trace and Deposit to Incentive trace) will not be created for any
Sum Incentive function. Only direct reference to the Incentive will have traces created.

21.2.11 Sum Deposits to Date and Sum Deposits to Date with

Status

Description: Use the two functions Sum Deposits to Date and Sum Deposits to Date with Status to total
deposits with the same name for a given period.

You can use this value in a condition statement so that incentive decisions can be based on it. The details
indicate which value and how much of it to sum.

 Note

Current period deposits will not be included when calculating the sum value for these functions.

Incentive Management Admin Design Guide

272 PUBLIC About Functions
Input:

• Deposit Name—to indicate which deposits to sum. Select String then enter the name of the deposit. You
must ensure that your entry matches the case and spacing of the deposit name.
• Period Type—the period in which to sum the deposit (for example, “year? to date).
• Deposit Status— to indicate by status, which deposits to the total, select the hold status: available, held,
both. (This applies only to the Sum Deposits to Date with Status function.)

Output:

• The sum of the calculated deposits

Example:

Calculate the deposits year to date less the amount paid so far.

The Formula as given below calculates the deposits year to date:

Sum Deposits to Date with Status = (Deposit Name (“Sr VP Quarterly Deposit?), Period Type (year), Deposit
Status (Available))

21.3 About Order-Level Functions Overview

Each function calculates data that represents summary information related to all the transactions on an order.
These functions are referred to as order-level functions. The following table describes the order-level functions.

Order-Level Functions

Function Name Description

Order Max Credit - DO/RO Maximum or minimum credit amount

Order Min Credit - DO/RO (cannot be used in a transaction-based credit rule or

formula)

Order Min Transaction - DO/RO/DC/RC Maximum or Minimum value of transactions

Order Max Transaction - DO/RO/DC/RC

Order Sum Credits - DO/RO Sum of transaction credits

Order Sum Transaction Units - DO/RO/DC/RC Sum of units of transactions

Order Sum Transactions - DO/RO/DC/RC Sum of values of transactions

Order Num Transactions - DO/RO/DC/RC Number of transactions

The following table contains the details that you input into the previous functions.

 Note

Only the credit value functions accept the details of credit type and credit held.

Incentive Management Admin Design Guide

About Functions PUBLIC 273
The order-level functions accept the details as shown in the following table.

Arguments for Order-Level Functions

Argument Possible Values

Event Type (any of the defined event types)

Any (accepts items regardless of event type)

territory, Category, Classi- a specific classifier assignment

fier
a specific category or subcategory

a specific territory

Any (accepts items regardless of territory and so forth)

Current Position Only? true: Select only transactions credited to current position assignment.

(Only Transactions credited false: Select transactions that are not credited to the current position assignment.
to current Position)
Any: Select transactions regardless of who received credit.

Period Type (any of the defined period types)

Any (accepts items regardless of period type)

Line Number Specify an integer (for example, type a number or point to a fixed value).

Any (accepts items regardless of line number)

Credit Type (any of the defined credit types)

Any (accepts items regardless of credit type)

Credit Held? true (the credit is currently held and not available)

false (the credit is not currently held and is available)

Any

How Empty Orders are Processed

The following order-level functions return a null if no data is returned:

• Order Max Credit - DO/RO

• Order Min Credit - DO/RO
• Order Min Transaction - DO/RO/DC/RC
• Order Max Transaction - DO/RO/DC/RC

The following order-level functions return a zero value if no data is returned:

• Order Num Transactions - DO/RO/DC/RC

• Order Sum Credits - DO/RO

Incentive Management Admin Design Guide

274 PUBLIC About Functions
• Order Sum Transactions - DO/RO/DC/RC
• Order Sum Transaction Units - DO/RO/DC/RC

21.3.1 Credit.Is Order Credit() and Source Credit.Is Order

Credit()

Description: Use these functions to determine whether a credit is based on an entire order (if it is not an order
credit, it is transaction-based). This function can also display as a data field in the Legal Moves listing as Source
Credit.Is Order Credit.

Input: None

Return Type: True or false (Boolean)

Example: Knowing if a Credit is an Order Level Credit is useful if you are creating a measurement that
aggregates Order Level Credits (you'd use this function in the condition field of the Measurement rule).

21.3.2 Order Max/Min Credit - DO/RO

Description: Use these two functions to calculate the maximum or minimum transaction credit value that
comes from an order. These two functions cannot be used in a transaction-based credit rule. The -DO or -RO
extension to the function names distinguish between the function for use in direct order credit rules (DO) and
rolled order credit rules (RO).

Input:

• Event Type
• Territory / Category / Classifier
• Current Position only? (Only Transactions credited to current Position)
• Period Type
• Line Number
• Credit Type
• Credit Held?

Output: A numeric value, with the same unit type as Min/Max credit value unit type in the order.

21.3.3 Order Max/Min Transaction - DO/RO/DC/RC

Description: These functions return the transaction value that is either the largest (max) or smallest (min) on
an order. The -DO, -RO, -DC, and -RC extension to the function names distinguish between the function for use
in direct order credit rules (DO), rolled order credit rules (RO), direct transaction credit rules (DC), and rolled
transaction credit rules (RC).

Incentive Management Admin Design Guide

About Functions PUBLIC 275
Input:

• Event Type
• Territory / Category / Classifier Assignment
• Current Position Only? (Only Transactions credited to current Position)
• Period Type
• Line Number

Output: A numeric value, with the same unit type as Max/Min Txn value on the order.

21.3.4 Order Sum Credits - DO/RO

Description: This function returns the sum of the transaction credits related to a specific order. This function
cannot be used in a transaction-based credit rule. The -DO or -RO extension to the function names distinguish
between the function for use in direct order credit rules (DO) and rolled order credit rules (RO).

Input:

• Event Type
• Territory / Category / Classifier
• Current Position Only? (Only Transactions credited to current Position)
• Period Type
• Line Number
• Credit Type
• Credit Held?

Output: A numeric value, with the same unit type as the sum of credit values on the order.

21.3.5 Order Sum Transaction Units - DO/RO/DC/RC

Description: This function calculates the total number of transaction units on an order. The -DO, -RO, -DC, and
-RC extension to the function names distinguish between the function for use in direct order credit rules (DO),
rolled order credit rules (RO), direct transaction credit rules (DC), and rolled transaction credit rules (RC).

Input:

• Event Type
• Territory / Category / Classifier
• Current Position Only? (Only Transactions credited to current Position)
• Period Type
• Line Number

Output: A numeric value of quantity unit type.

Incentive Management Admin Design Guide

276 PUBLIC About Functions
21.3.6 Order Sum Transactions - DO/RO/DC/RC

Description: This function calculates the sum of the transaction on an order. The -DO, -RO, -DC, and -RC
extension to the function names distinguish between the function for use in direct order credit rules (DO),
rolled order credit rules (RO), direct transaction credit rules (DC), and rolled transaction credit rules (RC).

Input:

• Event Type
• Territory / Category / Classifier Assignment
• Current Position? (Only Transactions credited to current Position for order credit rules only)
• Period Type
• Line Number

Output: A numeric value of quantity unit type.

21.3.7 Order Num Transactions - DO/RO/DC/RC

Description: This function calculates the number of transactions on an order. The -DO, -RO, -DC, and -RC
extension to the function names distinguish between the function for use in direct order credit rules (DO),
rolled order credit rules (RO), direct transaction credit rules (DC), and rolled transaction credit rules (RC).

Input:

• Event Type:
• Territory / Category / Classifier
• Current Position? (Only Transactions credited to current Position for order credit rules only)
• Period Type
• Line Number

Output: A numeric value of quantity unit type.

21.3.8 Transaction Line and Order Total() Functions

You can use the Transaction.Line Total() and the Order.Total() data field functions to retrieve the total value of a
transaction line or of an entire order. Remember that transactions are actually sublines on an order. These data
field functions take no input.

21.4 Text Search Functions Overview

All of the following are text search functions:

• String Contains

Incentive Management Admin Design Guide

About Functions PUBLIC 277
• String Ends With
• String Starts With
• Substring Between
• Substring From
• Substring Using Pattern

You can use these functions to look for a pattern or string in a field, such as a Generic Attribute field. You use
two types of functions: one type returns a true or false, and the other type returns the string itself, or a portion
thereof. You access the pattern search functions from the Legal Moves window. Searches can be case sensitive,
or not. You can search for plain text, or you can include advanced wildcard operators in your search criteria.
These advanced wildcard operators are commonly referred to as regular expressions. A regular expression is
an advanced search notation commonly used with databases and search engines.

There are many different variations for regular expression syntax. The system uses the PERL set, which is the
fullest set. Because of a third-party product interdependency, some characters should not be used in input
strings as they cause problems during calculation processing.

21.4.1 String Contains

Description: Looks for a particular string that contains the given pattern text.

Input: This function takes the following input parameters:

• String
• Pattern Text
• Case Sensitive?

Output: True or False (Boolean return type)

Example: For example, when a function searches for the pattern “Golf” (Pattern Text) in
Transaction.ProductDesc(String), the function returns “true” if the transaction’s Product Description includes
“Golf.” The function returns “false” if the pattern text is not found.

Formula: String Contains (Transaction.ProductDesc,”Golf”, false)

21.4.2 String Ends With

Description: Looks for a particular string that ends with the given pattern text.

Input: This function takes the following input parameters:

• String
• Pattern Text
• Case Sensitive?

Output: True or False (Boolean return type)

Example: For example, when a function searches for the pattern “Golf” (Pattern Text) in
Credit.Transaction.ProductDesc (String), the function returns “true” if the transaction’s Product ID ends with
the text “Golf”. The function returns “false”if the pattern text is not found.

Incentive Management Admin Design Guide

278 PUBLIC About Functions
Formula: String Ends With (Credit.Transaction.ProductDesc, “Golf”, true)

21.4.3 String Starts With

Description: Looks for a particular string that starts with the given pattern text.

Input: This function takes the following input parameters:

• String
• Pattern Text
• Case Sensitive?

Output: True or False (Boolean return type)

Example: For example, when a function searches for the pattern “951” (pattern text) in the
Transaction.Shipping.PostalCode (String), the function returns “true” if the transaction’s shipping address
postal code begins with “951”. The function returns “false”if the pattern text is not found.

Formula: String Starts With (Transaction.Shipping.PostalCode, “951”, false)

21.4.4 Substring Between

Description: Looks for and returns the largest portion of a particular string that starts at a given starting
character position and ends at a given ending character position.

If startIndex > string length or if endIndex < string length, an empty string is returned.

Input: This function takes the following input parameters:

• Source String (the string from which the substring is obtained)

• Start Index of the substring to be extracted
• End Index of the substring to be extracted

Output: A string (String return type)

Example: For example, when a function searches for the text that starts with the sixth field character
(startIndex) and ends at the seventh field character (endIndex) in Transaction.Shipping.PostalCode (string),
the function returns what it finds between the two character positions.

Formula: Substring Between (Transaction.Shipping.PostalCode, 6, 7)

21.4.5 Substring From

Description: Looks for and returns the portion of a string beginning with the character at the Start Index
position through the end of the string.

If the number given for the Start Index is greater than the length of the string, an empty string is returned.

Incentive Management Admin Design Guide

About Functions PUBLIC 279
Input: This function takes the following input parameters:

• Source String (the string from which the substring is obtained)

• Start Index of the substring to be extracted

Output: A string (String return type)

Example: SubString From (Transaction.ProductDesc, 6) could search the following Product Description string
fields:

Golf Putter Golf Driver Golf Set - Women’s Golf Beginner Set

The function would return the following strings:

Putter Driver Set - Women’s Beginner Set

Formula: SubString From (Transaction.ProductDesc, 6)

21.4.6 Substring Using Pattern

Description: Looks for and returns the largest portion of a particular string that matches the given pattern text.

Input: This function takes the following input parameters:

• String
• Pattern Text
• Case Sensitive?

Output: A string (String return type)

Example: For example, when a function searches for the pattern “UB4” (pattern text) in Transaction.Generic
Attribute 1 (string), the function returns the found pattern when the transaction contains “UB4” in that field.

Formula: Substring Using Pattern (Transaction.Generic Attribute 1, “UB4”, false)

21.5 Date Functions Overview

This section contains the following topics:

• Overview of the Date Functions

• Add Time to Date
• Calendar Start Date and Calendar End Date
• Convert Date to String
• Convert Number to Date
• Convert String to Date
• Fiscal Date
• Fiscal Period Start Date and Fiscal Period End Date
• Measure Time Between Dates

Incentive Management Admin Design Guide

280 PUBLIC About Functions
• Measure Time Overlap
• Measure Time Overlap Percentage
• Measure Periods Between Dates
• Measure Period Overlap
• Measure Period Overlap Percentage
• Calculation Run Date

Related Articles

• About Date Functions [page 281]

• Add Time to Date [page 283]
• Calendar Start Date and Calendar End Date [page 283]
• Convert Date to String [page 284]
• Convert Number to Date [page 284]
• Convert String to Date [page 284]
• Fiscal Date [page 285]
• Fiscal Period Start Date and Fiscal Period End Date [page 285]
• Measure Time Between Dates [page 286]
• Measure Time Overlap [page 287]
• Measure Period Overlap Percentage [page 289]
• Measure Periods Between Dates [page 288]
• Measure Period Overlap [page 288]
• Measure Period Overlap Percentage [page 289]

21.5.1 About Date Functions

The system can calculate or act based on date information using date functions and either the standard
calendar or your fiscal calendar. You can choose to specify a date in a date function in any of three ways:

• Enter a specific date (for instance, "01.03.2008")

• Pick a date from the using the Calendar field button (an easy way to enter a specific date)
• Specify a relative date (for instance, "3 months offset from fiscal quarter")

You can use date functions in formulas and in rule conditions. The dates specified in a date function must be
within the default effective dates as determined by the default calendar.

Null Date Processing

When the system encounters a null date that is used in a date calculation function, it inserts a specific date of
its own in place of the null date. If a rule processes a null date (meaning that no date is specified), the system
assumes the following:

• Start dates that are null are set to 12/31/1969 4:00 pm

Incentive Management Admin Design Guide

About Functions PUBLIC 281
• End dates that are null are set to 12/31/2200 4:00 pm

The system generates an error message in the log file when it encounters null dates.

As a result, during calculation processing, the system might generate a false credit and an error message in the
log file. A 'false' credit is one that you did not intend to create. The system might also not create the credit that
you intended to create.

For example, the following situation causes a false credit to be generated:

• Use a function that uses a date as input (such as Add Time to Date) in a compensation rule formula.
• Use a NULL date (such as Position.GenericDate1) as input to the function.

• Create a condition, such as:

If the result of the formula > April 30, 2008, create a credit

• Run the calculation. A false credit is generated.

When the date that is null is a start date, the system uses December 31st, 1969 4:00 pm. For null end dates, it
uses December 31st, 18969, 14:00 pm.

 Note

When specifying a fiscal date, the date must occur within the bounds of the periods defined in the sytsem..
Otherwise, the system returns an error.

 Note

If one of the date comparison or date overlap functions is used, then the aforementioned null date
processing does not apply. In the context of these functions, these date assumptions are considered invalid
for the purposes of the function.

For more information, see the details for the following functions:

• Measure Time Between Dates

• Measure Time Overlap
• Measure Time Overlap Percentage
• Measure Periods Between Dates
• Measure Period Overlap
• Measure Period Overlap Percentage

Example Dates

For each of the date calculation functions, you can read the example to see how the function works. For the
examples that use fiscal period information, assume the following fiscal period structure:

Date Calculation Example Fiscal Periods

Incentive Management Admin Design Guide

282 PUBLIC About Functions
Period Period Start Date Period End Date Number of Days in Period

Period1 January 10, 2008 February 8, 2008 30

Period2 February 9, 2008 March 9, 2008 30

Period3 March 10, 2008 April 8, 2008 30

First Quarter of Fiscal Year January 10, 2008 April 8, 2008 90

2008

21.5.2 Add Time to Date

Description: Adds calendar years, months, days, hours, or minutes to a given date.

Input:

• Date
• Value—An offset amount
• Unit of Time (Days, Hours, Minutes, Months, Quarters, Seconds, Weeks, Years)

 Note

This function returns the End Of Time constant (1/1/2200) if the input date is null.

Output: A date (Date return type)

Example: Give a sales representative extra credit for a transaction if the transaction’s compensation date falls
within three months of the position assignment’s start date.

Formula: Add Time to Date [Date (Position Processing Start Date (true), Offset(3), Unit of Time (Months)]

Use the formula in the condition: Valid Transaction.Compensation Date < “qualification date.?

21.5.3 Calendar Start Date and Calendar End Date

Description: Given a specified date, these two functions (Calendar Start Date, Calendar End Date) find the start
or end date of a specified span of calendar time. For example, the first day of a calendar month, or last day of a
calendar year.

Input:

• Date
• Period type
• Period Offset

Incentive Management Admin Design Guide

About Functions PUBLIC 283
  Note

These functions return the End Of Time constant (1/1/2200) if the input date is null and the Beginning of
Time constant (1/1/1900) if the period offset is null.

Output: The start or end date (depending on the function chosen) of the resultant span of calendar time (Date
return type).

Example: Process the rule if the first day of the calendar month (in which the participant started in the position)
is in the current period.

Formula: Calendar Start Date [Date (Position Processing Start Date), Period Type ( Months), Period Offset (0)]

21.5.4 Convert Date to String

Description: Converts a specified date from a field to a text string.

Input: For the input, specify a date field, such as Credit.Compensation Date or a function that returns a date.
Also, you can enter a literal in the format mm/dd/yyyy.

Output: A string (String return type) in the format m/d/yy, HH:MM AM/PM.

21.5.5 Convert Number to Date

Description: Converts a number to date format.

Input: An integer number in the format of YYYYMMDDHHMMSS or YYYYMMDD (in the latter case, assumes
the next six digits as zero).

 Note

This function returns the End Of Time constant (1/1/2200) if the input number is null.

Output: A date (Date return type)

Example: Input of 20080209152614; the output is 2/9/08 3:26 PM.

21.5.6 Convert String to Date

Description: Converts a text string to date object. The text string should be in the format appropriate for the
current locale (different date and time formats are used in different locales).

For example, if an English (United States) locale is used, the string must be in either of the following formats:

Date and time: "mm/dd/yy hh:mm am"

Date only: "mm/dd/yy"

Incentive Management Admin Design Guide

284 PUBLIC About Functions
  Note

If the date stored as a string is not exactly in the format of the current locale, the system generates an error
when you run the calculation.

Input: String

 Note

This function returns the End Of Time constant (1/1/2200) if the input date is null.

Output: A date in the format of the current locale (Date return type)

Example: With the current locale set to English (United States), the system converts a text string input of
02/09/07 3:26 pm to an output date of Feb 09 2007 3:26 pm.

21.5.7 Fiscal Date

Description: Returns the start or end date of a fiscal period.

Input: This function takes the following parameters:

• Period Type
• Period Offset
• Start Date or End Date

Output: A date (Date return type)

21.5.8 Fiscal Period Start Date and Fiscal Period End Date

Description: Given a specified date, these two functions find the start or end date of the fiscal period in which
the date exists.

Input:

• Date
• Period Type
• Period Offset

Incentive Management Admin Design Guide

About Functions PUBLIC 285
  Note

When you specify an offset, be sure that the fiscal calendar has defined the period that you offset to;
otherwise the sytsem generates an error.

 Note

These functions return the End of Time constant (1/1/2200) if the input date is null.

Output: The start or end date (depending on the function chosen) of the resultant fiscal period (Date return
type).

Example: Process the rule for the next four periods, starting with the position assignment’s start date for
credit.

Formula: “Date to begin policy?? = Fiscal Period Start Date [Fiscal Period Start Date (Position Credit Start
Date) Period Type (month) offset (3)]

“Date to end policy?? = Fiscal Period End Date [Date (Position Credit Start Date) Period Type (month) Offset
(3)]

21.5.9 Measure Time Between Dates

Description: Measures the amount of time between two specified dates.

Input:

• Start Date
• End Date
• Unit of Time
• Absolute? Use the absolute value of the result (t/f). Absolute value ignores whether or not a value is
negative. If false and end date is before start date, the system returns a negative value.

 Note

This function returns a zero if either the Start Date or End Date is null.

Output: A quantity of time (Return type = quantity), measured in the specified units. This function rounds up
when your date calculation spans more than one full unit of time.

Example: Pay one rate or amount if a delivery was made within ten minutes of a target time, another if it was
within 30 minutes, and another if more than 30 minutes (within = before or after target).

Formula: Measure Time Between Two Dates [Start Date (Transaction.Comp Date), End Date
(Transaction.AcctDate), Unit of Time(Minutes), Absolute? (true)]

Incentive Management Admin Design Guide

286 PUBLIC About Functions
21.5.10 Measure Time Overlap
Description: Measures the amount of time that two sets of dates overlap. If input parameters contain null
dates, this function works as follows:

• If both the Second Start Date and (First) Start date are null, or the Second End Date and (First) End date
are null, the function returns zero.
• If either the Second Start Date or (First) Start Date are null, the BOT constant (1/1/1900) is substituted for
the null date.
• If either the Second End Date or the (First) End Date are null, the EOT constant (1/1/2200) is substituted
for the null date.

Input:

• Start Date and End Date—Dates for time span #1. The (First) Start Date must be earlier than Second Start
Date, and (First) End Date must be earlier than Second End Date.
• Second Start Date and Second End Date—Dates for time span #2
• Unit of time

Output: A quantity of time, measured in the specified units (Quantity return type)

Example: Calculate the number of days a participant has been employed so far (as of the end of the month) for
the current year.

Formula: Measure Time Overlap ((First Start Date (Position Processing Start Date (true)), (First End Date
(Position Processing End Date (true))), ((Second Start Date (Fiscal Date (year, 0, Start Date)), Second End
Date (Fiscal Date (Month, 0, End Date,)), Unit of time (Days)]

21.5.11 Measure Time Overlap Percentage

Description: Measures the percentage of time that one set of dates overlaps another set of dates.

If input parameters contain null dates, this function works as follows:

• If either the (First) Start Date or (First) End Date, the function returns zero.
• If the Second Start Date is null, the BOT constant (1/1/1900) is substituted for the null date.
• If the Second End Date is null, the EOT constant (1/1/2200) is substituted for the null date.
• If both the Second Start Date and Second End Date are null, the BOT constant (1/1/1900) is substituted
for the null dates.

Input:

• (First) Start Date and (First) End Date—Dates for time span #1. The (First) Start Date must be earlier than
Second Start Date, and (First) End Date must be earlier than Second End Date.
• Second Start Date and Second End Date—Dates for time span #2
• Period Type
• Include Partial Periods?

Output: A percentage amount, measured in the specified units. (Percentage return type)

Example: Prorate a value based on the percentage of time worked during the current quarter (period),
measured in hours.

Incentive Management Admin Design Guide

About Functions PUBLIC 287
Formula: Measure Time Overlap Percentage [Start Date ((Position Processing Start Date (true)), End Date
(Position Processing End Date), Second start date (Fiscal Date (quarter, 0, Start Date)), Second end date
(Fiscal Date(quarter, 0, End Date)), Unit of time (month), Include partial periods (true)]

21.5.12 Measure Periods Between Dates

Description: Measures the number of fiscal periods that two dates span. This counts the number of periods
away the dates are from each other, not how many whole periods.

Two dates in the same period are a single, partial period (if include partial periods is true). If the dates are the
same, then the number of periods spanned is zero. The following figure shows an example of how this function
calculates the number of periods between two dates.

Input:

• Start Date
• End Date
• Period Type
• Include Partial Periods?
• Absolute?—Indicates whether or not to use the absolute value

 Note

This function does not work if any of the supplied dates are null. If any of the supplied dates to this function
are null, the system generates an error message and returns a result of zero.

 Note

This function returns a zero if either the Start Date or End Date is null.

Output: The number of periods measured in the specified period type (Quantity return type)

Example: Calculate the number of quarters in the current year.

Formula: Measure Periods Between Dates [Start Date (Fiscal Date (year, 0, Start Date)), End Date (Fiscal Date
(year, 0, End Date)) Period Type (quarter), Include Partial Periods? (false), Absolute? (true)]

21.5.13 Measure Period Overlap

Description: Measures the number of fiscal periods that one set of dates overlaps another set of dates.

It is common and acceptable for a position assignment’s end date to be null (not specified), as long as the
position assignment is active for all dates after the start date. If input parameters contain null dates, this
function works as follows:

• If both the Second Start Date and (First) Start date are null, or the Second End Date and (First) End date
are null, the function returns zero.
• If either the Second Start Date or (First) Start Date are null, the BOT constant (1/1/1900) is substituted for
the null date.

Incentive Management Admin Design Guide

288 PUBLIC About Functions
• If either the Second End Date or the (First) End Date are null, the EOT constant (1/1/2200) is substituted
for the null date.

Input:

• Start Date and End Date—Dates for time span #1. The (First) Start Date must be earlier than Second Start
Date, and (First) End Date must be earlier than Second End Date.
• Second Start Date and Second End Date—Dates for time span #2
• Period Type
• Include Partial Periods?

Output: A quantity, measured in the specified period type (Integer return type)

 Note

This function does not work if any of the supplied dates are null. If any of the supplied dates to this function
are null, the system generates an error message and returns a result of zero.

Example: Calculate the number of entire fiscal periods that the participant has been assigned to a position
(since the beginning of the fiscal year through the end of the current period).

Formula: Measure Period Overlap [Start date (Position Processing Start Date), End Date (Position Processing
End Date), Second Start Date (FiscalDate (year, 0, Start Date)), Second End Date (Fiscal Date (month, 0, End
Date)), Period Type (month), Include Partial Periods? (false)]

21.5.14 Measure Period Overlap Percentage

Description: Measures the percentage of the specified fiscal period that a given set of dates overlaps another
set of dates. It is common and acceptable for a position assignment’s end date to be null (not specified), as
long as the position assignment is active for all dates after the start date. If input parameters contain null dates,
this function works as follows:

• If either the (First) Start Date or (First) End Date, the function returns zero.
• If the Second Start Date is null, the BOT constant (1/1/1900) is substituted for the null date.
• If the Second End Date is null, the EOT constant (1/1/2200) is substituted for the null date.
• If both the Second Start Date and Second End Date are null, the BOT constant (1/1/1900) is substituted
for the null dates.

Input:

• Start Date and End Date—A start and end date for time span #1.The (First) Start Date must be earlier than
Second Start Date, and (First) End Date must be earlier than Second End Date.
• Second Start Date and Second End Date—A start and end date for time span #2
• Period type
• Whether or not to include partial periods

 Note

This function does not work if any of the supplied dates are null. If any of the supplied dates to this function
are null, the system generates an error message and returns a result of zero.

Incentive Management Admin Design Guide

About Functions PUBLIC 289
Output: A percentage, measured in the specified period type.

Example: Prorate something based on the percentage of full months (periods) worked during the current
quarter (as of the current month), measured in days.

Formula: “Prorate percentage?? = Measure Period Overlap Percentage [((Position Processing Start Date
(true)), (Positions Processing End Date (true)), (Fiscal Date (quarter, 0, Start Date)), (Fiscal Date (month,
0, End Date)), month, false)

21.5.15 Calculation Run Date

Description: This function returns the date that a calculation run started.

Input: No input is needed; the function simply returns a date.

Output: The date of a calculation run (Date return type)

21.6 Ranking Functions

Use the ranking functions when writing secondary measurement, incentive or deposit rules.

Overview of Ranking Functions

The functions calculate the rank of the given measurement or incentive for the current position in the
population.

Ranking Functions

Function Name Description

Rank By Measurement Ranking function available in secondary measurement, in-

centive and deposit rules which returns the rank of the given
measurement for the current position in the population.

Rank By Incentive Ranking function available in incentive and deposit rules

which returns the rank of the given incentive for the current
position in the population.

Total Population for Ranked Measurement Ranking function available in secondary measurement, in-
centive and deposit rules which returns the size of the rank-
ing population for the given measurement.

Incentive Management Admin Design Guide

290 PUBLIC About Functions
Function Name Description

Total Population for Ranked Incentive Ranking function available in incentive and deposit rules
which returns the size of the ranking population for the given
incentive.

The following table contains the details that you input into the ranking functions.

Arguments for Ranking Functions

Argument Possible Value

Measurement or Incentive Name Measurement or Incentive input reference used in ranking.

1st GA Index for Grouping Required parameter which specifies the first generic attrib-
ute index in the position that can be used to group the popu-
lation for ranking.

2nd GA Index for Grouping Optional parameter which specifies additional generic attrib-
ute index in the position that can be used to group the popu-
lation for ranking.

3rd GA Index for Grouping Optional parameter which specifies additional generic attrib-
ute index in the position that can be used to group the popu-
lation for ranking.

GB Index for Filtering Optional parameter which specifies the generic boolean in-
dex in the position that can be used to filtering out position
in the ranking. If set, all the position with ”r;false” or null
value in the specified generic boolean index will be excluded
from the ranking.

Use dense ranking? The required parameter which specifies the tie option. If
true, the next rank after the tie will be the next consecutive
(Only in "Rank by..." functions)
number. If false, the next rank after the tier will be the next
consecutive number plus number of tie. Example: if we have
to rank the values $300, $200, $200, $100, it will be ranked
as 1, 2, 2, 3.

Use descending ranking? The required parameter which specifies the sorting order
for the rank. If true, the measurement/incentive with the
(Only in "Rank by..." functions)
highest value will be ranked as number one. If set to false,
lowest value will be ranked as number one.

21.6.1 Rank By Measurement () and Rank By Incentive ()

Description: Use these functions to determine the rank of the given measurement or incentive for the current
position in the population.

Incentive Management Admin Design Guide

About Functions PUBLIC 291
Input:

• Measurement or Incentive
• 1st GA Index for Grouping
• 2nd GA Index for Grouping
• 3rd GA Index for Grouping
• GB Index for Filtering
• Use dense ranking?
• Use descending ranking?

Output: A quantity value, which corresponds to the current position rank.

Example:

Suppose there are 14 positions with the following attributes:

Generic Attrib- Generic Attrib- Generic Attrib- Generic Boo-

Position Name ute 1 ute 2 ute 3 lean 1 Incentive name Incentive Value

Position 1 District1 Team1 null true IR_AE Commis- $100

sion

Position 2 District1 Team1 null true IR_AE Commis- $200

sion

Position 3 District1 Team1 null true IR_AE Commis- $300

sion

Position 4 District1 Team1 null true IR_AE Commis- $400

sion

Position 5 District1 Team2 null true IR_AE Commis- $500

sion

Position 6 null null null null IR_AE Commis- $600

sion

Position 7 District1 Team2 null true IR_AE Commis- $600

sion

Position 8 District1 Team2 null false IR_AE Commis- $400

sion

Position 9 District1 Team2 null true IR_AE Commis- $300

sion

Position 10 District2 Team1 null true IR_AE Commis- $200

sion

Position 11 District2 Team1 null true IR_AE Commis- $300

sion

Incentive Management Admin Design Guide

292 PUBLIC About Functions
 Generic Attrib- Generic Attrib- Generic Attrib- Generic Boo-
Position Name ute 1 ute 2 ute 3 lean 1 Incentive name Incentive Value

Position 12 District2 Team2 null true IR_AE Commis- $400

sion

Position 13 District2 Team2 null true IR_AE Commis- $500

sion

Position 14 District2 Team2 null true IR_AE Commis- $600

sion

Rank By Incentive function is going to produce the following result:

Rank By Incentive (IR_AE Commission,

Position Name 1,2,Any,1,true,true)

Position 1 4

Position 2 3

Position 3 2

Position 4 1

Position 5 2

Position 6 -

Position 7 1

Position 8 -

Position 9 3

Position 10 2

Position 11 1

Position 12 3

Position 13 2

Position 14 1

Incentive Management Admin Design Guide

About Functions PUBLIC 293
21.6.2 Total Population for Ranked Measurement () and Total
Population for Ranked Incentive ()

Description: Use these functions to determine the size of the ranking population for the given measurement or
incentive.

Input:

• Measurement or Incentive
• 1st GA Index for Grouping
• 2nd GA Index for Grouping
• 3rd GA Index for Grouping
• GB Index for Filtering

Output: A quantity value, which corresponds to the size of the ranking population.

Example:

Suppose there are 14 positions with the following attributes:

Generic Attrib- Generic Attrib- Generic Attrib- Generic Boo-

Position Name ute 1 ute 2 ute 3 lean 1 Incentive name Incentive Value

Position 1 District1 Team1 null true IR_AE Commis- $100

sion

Position 2 District1 Team1 null true IR_AE Commis- $200

sion

Position 3 District1 Team1 null true IR_AE Commis- $300

sion

Position 4 District1 Team1 null true IR_AE Commis- $400

sion

Position 5 District1 Team2 null true IR_AE Commis- $500

sion

Position 6 null null null null IR_AE Commis- $600

sion

Position 7 District1 Team2 null true IR_AE Commis- $600

sion

Position 8 District1 Team2 null false IR_AE Commis- $400

sion

Position 9 District1 Team2 null true IR_AE Commis- $300

sion

Incentive Management Admin Design Guide

294 PUBLIC About Functions
 Generic Attrib- Generic Attrib- Generic Attrib- Generic Boo-
Position Name ute 1 ute 2 ute 3 lean 1 Incentive name Incentive Value

Position 10 District2 Team1 null true IR_AE Commis- $200

sion

Position 11 District2 Team1 null true IR_AE Commis- $300

sion

Position 12 District2 Team2 null true IR_AE Commis- $400

sion

Position 13 District2 Team2 null true IR_AE Commis- $500

sion

Position 14 District2 Team2 null true IR_AE Commis- $600

sion

Total Population for Ranked Incentive function is going to produce the following result:

Total Population for Ranked Incentive (IR_AE Commis-

Position Name sion, 1,2,Any,1)

Position 1 4

Position 2 4

Position 3 4

Position 4 4

Position 5 3

Position 6 -

Position 7 3

Position 8 -

Position 9 3

Position 10 2

Position 11 2

Position 12 3

Position 13 3

Position 14 3

Incentive Management Admin Design Guide

About Functions PUBLIC 295
21.7 Position Proration Functions

Description: New rules are added to accommodate customer’s needs like Pro-ration functions. Use the
following data field functions to calculate the number of days within a period or date range that a position
assignment is effective for calculation processing or credit allocation. If a period type is specified, the system
looks within the period type in which the date of the calculation run occurs.

• Position.Processing Days Between Dates()

• Position.Processing Days in Period()
• Position.Receiving Credit Days Between Dates()
• Position.Receiving Credit Days in Period()

If the position has multiple effective versions, the system looks for the combination of position and participant
(the position assignment) that is effective during the current period and looks at all effective versions of the
position for that position assignment.

For example, a position assignment’s processing dates are effective as follows:

Position processing effective 1/1/08 to 4/30/08: Mary assigned to Sales Rep Position

Position processing not effective 5/1/08 to 8/30/08: Mary on leave

Position processing effective again 9/1/08 to End Of Time: Mary assigned to Sales Rep Position

For this type of situation, the system looks for not just the current version of the position assignment, but also
previous versions of the same position assignment. In this case, if a rule used the Position.Processing Days in
Period (period type=year) function, the system would return the number of days between 1/1/08 to 4/30/08
and also the days from 9/1/08 to 12/31/08.

Input: Depending on the function that you are using, specify a period type or a start date and end date. (To
specify a period type, first enter "period type," and then specify the required period type.)

Output: An integer value (Integer return type).

Example: A bonus eligibility condition could be that participants must be assigned to their position (and
eligible for processing) for at least 80 days in the quarter. You could use the Position.Processing Days in Period
function to determine if the position assignment is eligible for the bonus.

The condition in the incentive rule would look as follows:

Position.Processing Days in Period (quarter) >= 80

Related Articles

• Participant Proration Function [page 297]

Incentive Management Admin Design Guide

296 PUBLIC About Functions
21.7.1 Participant Proration Function

Description: Three meta functions are provided to support the proration scenario:

• Participant.Start Date In Current Position()

• Participant.End Date In Current Position()
• Participant.Percentage of Days In Current Position()

Input: Null (no inputs required)

Output: Date and Percentage.

1. Participant.Start Date In Current Position()

Meta function on participant object returns the startDate of the position assignment. If there are multiple
versions of the position assigned to the participant, it returns the startdate on the first version of the position.

For example:

On 1/1, Mary was assigned the DM position, on 1/10, there is a change on the target Compensation on DM
position, so a new version of the position was created. On 1/15, Mary was promoted on a new position and John
was assigned with the DM position. Also Mary's on DM Position's processingDate was extended to End of year.

VP Position <---------v1---------> EffDate

Mary

DM Positon <----- v1 -------><------ v2 ----><------- v3 ---------> EffDate |------------------------------------>

ProcessingDate

1/1/99 Mary 1/10/99 Mary 1/15/99John 1/1/00

When calculation was running on December, we would have three BusinessNode as follow:

1. BN1(DM, Mary)
2. BN2(DM, Jonh)
3. BN3(VP, Mary)

• BN1's startDateInCurrentPosition would be 1/1/99

• BN2's startDateInCurrentPosition would be 1/15/99
• BN3's startDateInCurrentPosition would be 1/15/99

2. Participant.End Date In Current Position()

Meta function on participant object returns the endDate of the position assignment. If there are multiple
versions of the position assigned to the participant, it returns the enddate on the last version of the position.

For example:

On 1/1, Mary was assigned the DM position, on 1/10, there is a change on the targetCompensation on DM
position, so a new version of the position was created. On 1/15, Mary was promoted on a new position and John
was assigned with the DM position. Also Mary's on DM Position's processingDate was extended to End of year.

VP Position <---------v1---------> EffDate

Mary

DM Positon <----- v1 -------><------ v2 ----><------- v3 ---------> EffDate |------------------------------------>

ProcessingDate

Incentive Management Admin Design Guide

About Functions PUBLIC 297
1/1/99 Mary 1/10/99 Mary 1/15/99John 1/1/00

When calculation was running on December, we would have three BusinessNode as follow:

1. BN1(DM, Mary)
2. BN2(DM, Jonh)
3. BN3(VP, Mary)

• BN1's endDateInCurrentPosition would be 1/15/99

• BN2's endDateInCurrentPosition would be 1/1/00
• BN3's endDateInCurrentPosition would be 1/1/00

3. Participant.Percentage of Days In Current Position()

Calculates the percentage of days the participant was in the current position for the current processing period.
To implement proration, the above function will be used in conjunction with the Date function such as Measure
Time Overlap Percentage.

BN1.v1.targetComp = $100k

BN1.v2.targetComp = $110k

BN2.targetComp = $150k

BN3.targetComp = $200k

BN4.targetComp = $500k

Annual Bonus:

val = PercentageTimeOverlap(Participant.StartDateInCurrPos, Participant.EndDateInCurrPos, 1/1/99, 1/1/00)

Position.targetComp * 5%

BN1(DM, Mary) = ( 221 / 365 ) * 110k * 5% = $3,330.14

BN2(DM, Jonh) = (144 / 365 ) * 150k * 5% = $2,958.90

BN3(VP, Mary) = (144 /365) * 200k * 5% = $3,945.21

BN4(SVP, George) = (11 / 365) * 500k * 5% = $753.42

MBO Bonus for Dec:

val = PercentageOfDaysInCurrentPosition() * Position.salary * 1%

BN1(DM, Mary) = (0 / 31) * 110k * 1% = $0.00

BN2(DM, John) = (31 / 31) * 150k * 1% = $1,500.00

BN3(VP, Mary) = (31 / 31) * 200k * 1% = $2,000.00

BN4(SVP, George) = (11 / 31) * 500k * 1% = $1,774.19

Incentive Management Admin Design Guide

298 PUBLIC About Functions
21.8 Query Functions

Query Functions

The query functions allow you to execute queries during the pipeline run, instead of writing custom store
procedures. The data retrieved from these queries can be further used by the professional services team to
create a custom SQL query to extend the functionality of the product.

The following parameters are the same for all query functions:

• Name of the query (required)

• String parameter that can be referenced in the query (optional)
• String parameter that can be referenced in the query (optional)
• Value parameter that can be referenced in the query (optional)
• Value parameter that can be referenced in the query (optional)
• Boolean parameter that can be referenced in the query(optional)
• Boolean parameter that can be referenced in the query(optional)
• Date parameter that can be referenced in the query (optional)
• Date parameter that can be referenced in the query (optional)
• Default value that is returned if the query returns no result or null (optional)

Important points to note about the custom SQL query:

• The query can put in the compensation rule.

• The query supports all the common return types, such as Value, Number String, Date and Boolean.
• The query can reference context values, such as current period, current transaction, current position, and
current payee in the SQL.
• The query can reference user provided parameters that are to be used in the SQL.
• DML or DDM operations in the SQL, such as Update, Delete, Insert, Create, Alter, etc. are restricted.
• The query is not visible in the UI.
• The query is timed out if it runs longer than 5 seconds.
• The query is profiled.

Example of the Query for Value function:

See Example Usage: Query for Value [page 303] for more details.

 Note

When writing the SQL query for the Query Function, make sure you insert a space in between each token of
the SQL because the SQL parsing uses the space as the delimiter to detect the tokens.

For example, the following SQL will not work because there is no space before the token $positionName:

SELECT targetCompensation, unitTypeForTargetCompensation FROM CS_Position WHERE name

=$positionName

Incentive Management Admin Design Guide

About Functions PUBLIC 299
 Instead, the correct SQL should be (that is, with space before the $positionName token):

SELECT targetCompensation, unitTypeForTargetCompensation FROM CS_Position WHERE name =

$positionName

Limitations

• QueryFunction will not work if you are querying Secondary Measurement, Incentive, Commission, or
Deposit results for different positions or across positions because different positions can be processed in
different process workers, so the results may not be calculated when the QueryFunction is evaluated.
• When querying Secondary Measurement, Incentive, Commission, or Deposit for the same position, you
must ensure that the result you are querying is already evaluated when the query is executing. This can be
done by adding a reference to the Output of the Rule in the Rule where you have the QueryFunction. This
ensures that the Pipeline evaluates the Rule that the QueryFunction depends on first.

21.8.1 Query for Value

Description: Use this query in the compensation rule or formula. This function runs the query specified in the
first parameter and returns back a Value object (a double value with a unitType).

The implementation of this query is specified in the CS_PlugInQuery table by the professional services team.

Context Variables: The following context variables can be used to reference values in the current processing
context:

• $pipelineRunSeq - current pipeline run's pipelineRunSeq

• $pipelineRunDate - current pipeline run's startTime
• $modelSeq - current pipeline run's modelSeq
• $periodSeq - current pipeline run's periodSeq
• $calendarSeq - current pipeline run's calendarSeq
• $processingUnitSeq - current pipeline run's processingUnitSeq
• $periodStartDate - current pipeline run period's startDate
• $periodEndDate - current pipeline run period's endDate
• $lastDateInPeriod - current pipeline run period's lastDate (i.e. endDate minus one second)
• $tenantId - current tenantId
• $positionSeq - current position in the processing
• $positionName - name of the current position in the processing
• $positionEffectiveStartDate - effectiveStartDate of the current position in the processing
• $positionEffectiveEndDate - effectiveEndDate of the current position in the processing
• $positionProcessingStartDate - processingStartDate of the current position in the processing
• $positionProcessingEndDate - processingEndDate of the current position in the processing
• $positionCreditStartDate - creditStartDate of the current position in the processing
• $positionCreditEndDate - creditEndDate of the current position in the processing

Incentive Management Admin Design Guide

300 PUBLIC About Functions
• $payeeSeq - current payee in the processing
• $ruleSeq - current rule in the processing
• $planSeq - current plan in the processing
• $salesTransactionSeq - current sales transaction in the processing (only apply in Allocate stage)
• $compensationDate - compensation date of the current sales transaction in the processing (only apply in
Allocate stage)
• $salesOrderSeq - current sales order in the processing (only apply in Allocate stage)
• $creditSeq - current credit in the processing (only apply in Allocate stage)

Parameter Variables: The following parameter variables can be used as values in the input parameter of the
query function:

• $1 - value of the first String parameter in the Query function. (first String parameter)
• $2 - value of the second String parameter in the Query function (second String parameter)
• $3 - value of the first Value parameter in the Query function (first Value parameter)
• $4 - value of the second Value parameter in the Query function (second Value parameter)
• $5 - value of the first Boolean parameter in the Query function (first Boolean parameter)
• $6 - value of the second Boolean parameter in the Query function (second Boolean parameter)
• $7 - value of the first Date parameter in the Query function (first Date parameter)
• $8 - value of the second Date parameter in the Query function (second Date parameter)

Input: Query from the first parameter.

Output: A value object.

Formula: Query for Value (<query name>, <string parameter>, <string parameter>, <value parameter>, <value
parameter>, <boolean parameter> , <boolean parameter>, <date parameter>, <date parameter>, <default
values>)

The constraint of the query:

• Only the SELECT SQL function is allowed, any other type of SQL like INSERT, UPDATE, DELETE will fail.
• The query has to finish within 5 seconds, or it will be canceled. (The query will be terminated and the
pipeline will continue.)
• Query has to project (i.e. select) two columns, first column is the value and second column is the
unitTypeForValue (Example: select value, unitTypeForValue from CS_SalesTransaction).
• If the query returns multiple rows, only the first row's value will be returned.
• Avoid using a query that aggregates results for Secondary Measurements, Incentives, and Deposits for
the current period. For example, sum of the Secondary Measurement value for the current period. This
is because the result will be calculated with multiple workers and some workers may not have the
results calculated when the query was executed. If there is no other option and you have to use it, a
possible workaround is to put a Ranking function on this result in the Rule. For example, put a "Rank By
Measurement()"" function in the Generic Value field. This will provide an indication to the rule engine that it
needs to synchronize this result across all the workers.

Related Information

Query for Value [page 300]

Incentive Management Admin Design Guide

About Functions PUBLIC 301
Example Usage: Query for Value [page 303]

21.8.2 Query for String

Description: Use this query in the compensation rule or formula. This function runs the given query in the first
parameter and returns a String object.

Input: Query from the first parameter. Input parameters are similar to the Query for Value [page 300] function.

Output: A string object.

Formula: Query for String (<query name>, <string parameter>, <string parameter>, <value parameter>,
<value parameter>, <value parameter>, <boolean parameter>, <boolean parameter>, <date parameter>,
<date parameter>, <default value>)

The constraint of the query:

• Only "SELECT" SQL is allowed, any other type of SQL like "INSERT, UPDATE, DELETE" will fail.
• The query has to finish within 5 seconds, or it will be canceled. (The query will be terminated and the
pipeline will continue.)
• Query has to project (i.e. select) one column of type varchar2 (Example: select productId from
CS_SalesTransaction where salesTransactionSeq = $salesTransactionSeq).
• If the query returns multiple rows, only the first row's value will be returned.

Related Information

Example Usage: Query for Value [page 303]

21.8.3 Query for Boolean

Description: Use this query in the compensation rule or formula. This function runs the given query in the first
parameter and returns a Boolean object.

Input: Query from the first parameter. Input parameters are similar to the Query for Value [page 300] function.

Output: A boolean object.

Formula: Query for Boolean (<query name>, <string parameter>, <string parameter>, <value parameter>,
<value parameter>, <boolean parameter> , <boolean parameter>, <date parameter>, <date parameter>,
<default values>)

The constraint of the query:

• Only the SELECT SQL query is allowed, any other type of query such as INSERT, UPDATE, DELETE will fail.
• The query has to finish within five seconds, or it will be canceled. (The query will be terminated and the
pipeline will continue.)

Incentive Management Admin Design Guide

302 PUBLIC About Functions
• Query has to project (i.e. select) two columns, first column is the value and second column is the
unitTypeForValue (Example: select value, unitTypeForValue from CS_SalesTransaction).
• If the query returns multiple rows, only the first row's value will be returned.

Related Information

Example Usage: Query for Value [page 303]

21.8.4 Query for Date

Description: Use this query in the compensation rule or formula. This function runs the given query in the first
parameter and returns a Date object.

Input: Query from the first parameter. Input parameters are similar to the Query for Value [page 300] function.

Output: A date object.

Formula: Query for Date(<query name>, <string parameter>, <string parameter>, <value parameter>,<value
parameter>, <boolean parameter> , <boolean parameter>, <date parameter>, <date parameter>, <default
values>)

The constraint of the query:

• Only the SELECT SQL query is allowed, any other type of query such as INSERT, UPDATE, DELETE will fail.
• The query has to finish within 5 seconds, or it will be canceled. (The query will be terminated and the
pipeline will continue.)
• Query has to project (i.e. select) one column of type Date (Example: select compensationDate from
CS_SalesTransaction where salesTransactionSeq = $salesTransactionSeq).
• If the query returns multiple rows, only the first row will be returned.

Related Information

Example Usage: Query for Value [page 303]

21.8.5 Example Usage: Query for Value

This topic explains using the Query for Value function to implement the logic to sum all the prior period sales
transaction values for the current sales order for tenant TNTA.

1. Add the query to the CS_PlugInQuery table. Login as the TNTAEXT user and issue the following insert
statement:

Incentive Management Admin Design Guide

About Functions PUBLIC 303
  Sample Code

INSERT INTO CS_PlugInQuery (tenantId, name, query)

VALUES (
'TNTA',
'Sum Prior Period Transactions In Order',
'select sum(value), unitTypeForValue from CS_SalesTransaction
where salesOrderSeq = $salesOrderSeq and compensationDate <
$periodStartDate
group by unitTypeForValue')

2. Use the Query function in the Credit Rule and specify the name of the query populated in step 1:

 Note

A default value of $0.00 (last parameter) is put to handle the case when the query doesn't return any
result. $0.00 will be returned in this case.

3. During the pipeline run, the query specified in the query function is executed. It returns the value and use in
the Credit rule evaluation:

 Sample Code

ACTIONS
My Credit= RESULT( DIRECT_TRANSACTION_CREDIT_ALLGAs )
queryForValue
Sum Prior Period Transactions In Order
null
null
null
null
null
null
null
null
0 USD
JDBC: select sum(value), unitTypeForValue from CS_SalesTransaction where
salesOrderSeq = 14355223812243459 and compensationDate < to_date('February
1, 2006 12:00:00 AM', 'Month dd, yyyy HH:MI:SS AM' ) group by
unitTypeForValue
= RESULT( 200 USD )

Best Practices:

• Use the context variable (Example: $periodStartDate, $periodEndDate) instead of the parameter variable
($1 to $8), if possible. This will perform better because the query doesn't need to process the input
parameter. It also makes your query less dependent on the user provided value which can be changed.
• Provide a default value for your function so that the log file does not generate warning messages for null
values.
• If you have a complex query that needs to join many tables or a query with large volume of data, use a
stage hook to pre-generate the result in bulk and populate it in the EXT table and then use the Query

Incentive Management Admin Design Guide

304 PUBLIC About Functions
 function to query the result from that table. This will significantly improve the performance, while allow the
query to process each SalesTransaction for each Rule in the Allocate stage.
• To query the active version of an auditable object (that is, an object with createDate and removeDate),
use $pipelineRunDate to select the active object as follows: createDate <= $pipelineRunDate AND
removeDate > $pipelineRunDate.
• Avoid using date literals (for example, 2200-01-01) in the date parameter, as date literals are stored as
timestamps in the backend and include a time zone value.

Related Information

Query Functions [page 299]

Query for Value [page 300]
Query for String [page 302]
Query for Boolean [page 302]
Query for Date [page 303]

21.8.6 Groovy Function for Custom Queries

You can use the Groovy Function to build a Custom Query Function. This feature helps build logic for input
parameters, for example, formatting input data.

 Note

Currently, the usage of Groovy Function is supported only for importing java.text. packages.

An example of how to use the "Query for Value" function to implement the logic to "sum all the prior period sale
transaction value for current sales order" for tenant TNTA is illustrated below.

1. Add the query to the CS_PlugInQuery table. Log in as the TNTAEXT user and issue the following insert
statement:

 Sample Code

INSERT INTO CS_PlugInQuery (tenantId, name, query)

VALUES (
'TNTA',
'Sum Prior Period Transactions In Order',
'select sum(value), unitTypeForValue from CS_SalesTransaction
where salesOrderSeq = $salesOrderSeq and compensationDate <
$periodStartDate
group by unitTypeForValue')

The groovy function must have a main method with the signature def main($1, $2, $3, $4, $5, $6, $7, $8,
$9)

Incentive Management Admin Design Guide

About Functions PUBLIC 305
 $1 to $9 are input parameters from the Query Function, the parameter name can be anything, for example,
you can name it p1 to p9 instead of $1 to $9 as long as you have the same number of input parameters. The
value for $1 and $9 will be from the Query function as follows:
• $1 - value of the first String parameter in the Query function. (first String parameter).
• $2 - value of the second String parameter in the Query function (second String parameter).
• $3 - value of the first Value parameter in the Query function (first Value parameter). The Value
parameter is of type Array with $3[0] the BigDecimal value and $3[1] the UnitType name.
• $4 - value of the second Value parameter in the Query function (second Value parameter). The Value
parameter is of type Array with $3[0] the BigDecimal value and $3[1] the UnitType name.
• $5 - value of the first Boolean parameter in the Query function (first Boolean parameter).
• $6 - value of the second Boolean parameter in the Query function (second Boolean parameter).
• $7 - value of the first Date parameter in the Query function (first Date parameter). The Date parameter
is of type java.util.Date
• $8 - value of the second Date parameter in the Query function (second Date parameter). The Date
parameter is of type java.util.Date
• $9 - default value specified in the Query Function
Following is an example of a Groovy Function to format the input parameter to a text string:

 Sample Code

import java.text.*
def main($1, $2, $3, $4, $5, $6, $7, $8, $9) {
DecimalFormat df = new DecimalFormat("#,###.00");
if ($1 == 'TEXT') {
if ($3[0] == null){
return null
} else {
def s = $3[0].toString()
return s.substring(0, s.indexOf('.'))
}
} else if ($1 == 'DATE'){
if ($7 == null){
return '01/01/2200'
} else {
SimpleDateFormat sm = new SimpleDateFormat('MM/dd/yy')
return sm.format($7)
}
} else if ($1 == 'QUANTITY'){
if ($3[0] == null){
return '0.00'
} else {
return df.format($3[0].setScale(2, java.math.RoundingMode.CEILING))
}
} else if ($1 == 'MONEY'){
if ($3[0] == null){
return '$0.00'
} else {
return '$' + df.format($3[0].setScale(2,
java.math.RoundingMode.CEILING))
}
} else if ($1 == 'PERCENT'){
if ($3[0] == null){
return '0.00%'
} else {
return $3[0].multiply(new BigDecimal(100)).setScale(2,
java.math.RoundingMode.CEILING).toString()+'%'
}
} else {
return ''

Incentive Management Admin Design Guide

306 PUBLIC About Functions
 }
}

You can add this function to the CS_PlugInQuery with the insert SQL as follows:

 Sample Code

INSERT INTO CS_PLUGINQUERY (tenantId, name, query) VALUES ( 'TNTA',

'Format Value',
'import java.text.*
def main($1, $2, $3, $4, $5, $6, $7, $8, $9) {
DecimalFormat df = new DecimalFormat("#,###.00");
if ($1 == ''TEXT'') {
if ($3 == null){
return null
} else {
def s = $3[0].toString()
return s.substring(0, s.indexOf(''.''))
}
} else if ($1 == ''DATE''){
if ($7 == null){
return ''01/01/2200''
} else {
SimpleDateFormat sm = new SimpleDateFormat(''MM/dd/yy'')
return sm.format($7)
}
} else if ($1 == ''QUANTITY''){
if ($3[0] == null){
return ''0.00''
} else {
return df.format($3[0].setScale(2, java.math.RoundingMode.CEILING))
}
} else if ($1 == ''MONEY''){
if ($3[0] == null){
return ''$0.00''
} else {
return ''$'' + df.format($3[0].setScale(2,
java.math.RoundingMode.CEILING))
}
} else if ($1 == ''PERCENT''){
if ($3[0] == null){
return ''0.00%''
} else {
return $3[0].multiply(new BigDecimal(100)).setScale(2,
java.math.RoundingMode.CEILING).toString()+''%''
}
} else {
return ''''
}
}');

2. Use the Query function in the Credit Rule and specify the name of the query as shown in Step 1:

In this example, a default value of $0.00 (last parameter) is used to handle the query when it doesn't
return any result, so it will now return the value $0.00. SalesTransaction.compDate is also used as an input
parameter and is used in the query as the parameter variable $3. As a good practice, it is recommended to
use the known context variable.

Incentive Management Admin Design Guide

About Functions PUBLIC 307
 Example of a Groovy function:

3. During the pipeline run, the query specified in the "Query function" will be executed and it will return the
value and use it in the Credit rule evaluation:

 Sample Code

ACTIONS
My Credit= RESULT( DIRECT_TRANSACTION_CREDIT_ALLGAs )
queryForValue
Sum Prior Period Transactions In Order
null
null
null
null
null
null
null
null
0 USD
JDBC: select sum(value), unitTypeForValue from CS_SalesTransaction where
salesOrderSeq = 14355223812243459 and compensationDate < to_date('February
1, 2006 12:00:00 AM', 'Month dd, yyyy HH:MI:SS AM' ) group by
unitTypeForValue
= RESULT( 200 USD )

Best Practice

• Use the context variable (Example: $periodStartDate, $periodEndDate) instead of the parameter variable
($1 to $8) if possible. This will perform better because it doesn't need to process the input parameter. It will
also make your query less dependent on the user provided value, which can be changed.
• Provide default value for your function to reduce the warnings in the log file for null value.
• If you have a complex query that needs to join many tables or query large volumes of data, use a stage
hook to pregenerate the result in bulk and populate it in the EXT table and then use the Query function to
query the result from that table. The query runs when processing each SalesTransaction for each Rule in
Allocate stage and will improve the performance significantly.

Incentive Management Admin Design Guide

308 PUBLIC About Functions
22 Extending Product Functionality Using
Query Functions

Query Functions can provide some extended functionality that the system does not otherwise provide. See
Query Functions [page 299] for details.

Incentive Management Admin Design Guide

Extending Product Functionality Using Query Functions PUBLIC 309
23 Calculations Overview

You run the calculation to create results data typically at least once a period. You do not see results data until
you have run the calculation at least once.

Navigate to Review Calculations > Calculations to access the Calculations workspace. See the Administrative
Tasks documentation for information on running calculations. In the Calculations workspace, transaction data
(orders and transactions) and results data (credits, measurements, incentives, commissions, deposits, and
payments) are also accessible.

Related Articles

• Orders, Transactions, and Credits in Tree View [page 310]

• About Orders [page 311]
• About Transactions [page 313]
• About Credits [page 321]
• About Measurements [page 331]
• About Commissions [page 335]
• About Deposits [page 336]

23.1 Orders, Transactions, and Credits in Tree View

In tree view, the Orders, Transactions, and Credits workspaces are similar. In all three, you can view the
relationships between orders, transactions, and credits. You can expand the tree view to see the transactions
that belong to each order, and the credits that are associated with each transaction. All objects - imported,
manually created, or, in the case of credits, created by TrueComp - are displayed.

Navigate to Review Calculations > Calculations to access the respective workspaces.

 Note

If you do not have read permissions to Orders, the tree view is not available from the toolbar in the
Transactions or Credits workspaces.

In the Transactions and Credits workspaces, objects can also be viewed in table view. The Orders workspace
does not have a table view. If you search for a subset of the records (for example, all credits over a certain
value), the tree view shows only the objects related to the ones that satisfy the query. For example, you would
see only the orders and transactions that had credits over a certain value.

Incentive Management Admin Design Guide

310 PUBLIC Calculations Overview
Manual orders, manual transactions, and manual credits - which are created in the system, rather than
imported from an outside source - can be created in the tree view of all three workspaces as follows:

• To create a transaction related to a specific order, select the order and choose New.
• To create a credit related to a specific transaction, select the transaction and choose New.
• To create an order, deselect all objects using Ctrl + left-click , and then choose New.

23.2 About Orders

Orders are used to group transactions, and they are the basis of order credits. Orders can be imported with
transactions.

Related Articles

• Orders Workspace [page 311]

• Creating an Order [page 312]
• Finding Transactions and Credits Related to Orders [page 313]

23.2.1 Orders Workspace

Navigate to Calculations > Orders to access the Orders workspaces.

Orders Summary

The Summary pane in the Orders workspace can be viewed only in list view.

Order Deatils

The detail pane of the Orders workspace can contain General Information and Transactions tab.

The Custom attributes tab is displayed depending on whether or not the administrator has enabled custom
attributes for orders

The following figure shows the Orders workspace.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 311
If several transactions are associated with the order and these transactions have different unit types, the values
of the transactions with common unit types are subtotaled and displayed in the Total field. For example, if an
order has six transactions in US dollars and two in yen, the dollar and yen values are subtotaled and displayed
in the Total field.

23.2.2 Creating an Order

You can create an order from the Orders and Transactions workspaces.

Procedure

1. Navigate to Calculations > Orders.

2. Choose Create.
3. Type the Order ID in the details panel. If your organization has created and implemented business units,
you can assign this rule to a business unit by selecting from the Business Units drop-down. Orders can be
assigned to only one business unit. You can only select a business unit to which you as a user have been
assigned. If the administrator has enabled custom attributes for orders, Custom attributes section is visible
in general information tab to enter values in those fields.
4. Choose Save.
5. Choose Transactions to see assigned transactions to a particular order.

 Note

You can move a transaction to an order by modifying the transaction’s order ID.

 Note

After an order is either imported or created in the system, you cannot delete it. You can delete manual
transactions, however.

Incentive Management Admin Design Guide

312 PUBLIC Calculations Overview
23.2.3 Finding Transactions and Credits Related to Orders

You can find transaction and credit data related to one or more orders by selecting the appropriate object
option from the Related pane.

Procedure

1. Navigate to Calculations > Orders.

2. Search for the order or orders to which you want to find related objects.
3. Select the order or orders to which you want to find related transactions or credits in the Summary panel.
4. Select Transactions or Credits in the Related panel. The Search For Advanced Related Objects dialog
displays the name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Transactions—returns the transactions referring to the selected order.

• Credits—returns the credits referring to the selected order.

23.3 About Transactions

Transactions are the basis for direct and rolled transaction credits, which are allocated to position assignments.
Transactions are usually imported into the system from an external system, but can also be manually entered.
Transactions and their associated orders can be imported.

Related Articles

• Transactions Workspace [page 313]

• Creating a Manual Transaction [page 314]
• Specifying Payee Pre-Assignments [page 317]
• Modifying Transactions [page 318]
• Removing a Payee Pre-Assignment [page 318]
• Adjusting Transactions [page 319]
• Copying Transactions [page 320]
• Finding Objects Related to Components [page 98]

23.3.1 Transactions Workspace

Navigate to Calculations > Transactions to access the Transactions workspaces.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 313
The Transactions workspace can be viewed in list view. The Transactions workspace can contain four tabs:

Transaction Summary

You can view transactions and create manual transactions. (A manual transaction is a transaction created in
the system and is not imported from an outside source.) . You can also modify existing transactions. To modify
a transaction is to change a specific field that does not affect the transaction’s value.

Transaction Details

You can edit details in the General Information tab. You can also modify or adjust one or more existing
transactions. To modify a transaction is to change a specific field that does not affect the transaction’s values.

From the Addresses tab, you can enter and modify Billing, Shipping, and Other Addresses.

From the Participants Associated to the Transaction tab, you can optionally specify information related to the
position that should receive credit for the transaction.

The Custom Attributes tab is displayed depending on whether or not the administrator has enabled custom
attributes for transactions.

23.3.2 Creating a Manual Transaction

If you do not import transactions, you can create manual transactions. You can also create manual transactions
if you need to create placeholders for credits.

Incentive Management Admin Design Guide

314 PUBLIC Calculations Overview
Procedure

1. Choose Calculations > Transactions.

2. Choose Create. The detail panel displays fields for the new transaction.
3. Enter the transaction information.

Field Description

Order (Required) The order identification number to which the created transaction belongs.

Line (Required) The line number to which the created transaction belongs.

Subline (Required) The subline number.

Event Type (Required) Choose one of these user-defined event types to describe the kind of event that
precipitated the transaction. For example, booking or shipping.

Alt Order ID The alternate order ID. This ID can be used to track third-party sales order numbers.

Compensation (Required) The date when the transaction is effective for processing. You can enter a date or select
Date a date using the Calendar field button.

Acct Date The date the transaction occurred. You can enter a date or select a date using the Calendar field
button. The system defaults this to the current date.

Channel The name of the channel through which the product was sold.

PO Number The customer’s purchase order number.

Terms The payment terms of the transaction.

Reason Code A code that indicates the reason for the credit. Reason codes must be created by the administra-
tor.

Origin Type (Read-only) The system sets this field to report whether the deposit was calculated, imported, or
manually created.

Business Units (Read-only) The system automatically sets the business unit on the transaction to match the
business unit assignment on the order.

Comments Enter any applicable description or comments.

Product ID The product’s identification number or string. (Currently, you must enter this information man-
ually.)

Product Name The name of the product. (Currently, you must enter this information manually.)

Product Descrip- A short description of the product.

tion

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 315
 Field Description

Num Units The number of product units sold. You can enter a decimal value if the scale of your quantity unit
type is not zero. A decimal value might be required if two salespeople working together on a sale,
must be credited for the sale of half (0.5) a unit.

Unit Value The value of each product unit. Choose the Unit Type button to select a unit type. The options are
currency, percent, quantity, and integer.

Value (Required) The value of the transaction. Choose the Unit Type button to select a unit type. The
options are currency, percent, quantity, and integer.

Preadjusted (Read-only) The amount of the transaction before any adjustments have been made. The system
populates this with the initial transaction’s value.

Native Amount If the value is in another currency, you can enter that amount here. If more than one currency unit
type has been defined, choose the Unit Type button to select a unit type.

Native Currency (Read-only) The currency value for the Native Amt.

Discount The percentage amount of any applicable discount.

Discount Type If you specify a discount, specify the type here.

Data Source Indicates where the transaction originated from. For example, from the third-party order entry
system.

Runnable Whether or not the transaction is available to be processed by the calculation. The system auto-
matically marks a new transactions as runnable.

4. (Optional) Choose the Addresses tab and enter the address details: You can search for addresses
based on the above address fields. (Optional) To specify payee preassignments, click the Payee Pre-
Assignment(Participants Associated to the Transaction) tab.

Address Type Description

Billing (click Add Address to display the Billing fields) The customer’s billing address.

Shipping (click Add Address to display the Shipping fields) The customer’s shipping address.

Other (click Add Address to display the Other To fields) If applicable, another relevant customer address.

5. Choose Save.

 Note

• If the administrator has enabled custom attributes for transactions, custom attributes are visible in
general information tab
• If the administrator has enabled reporting attributes for the Transactions workspace, Reporting
Attributes section is visible in the general information tab, to enter values in those fields.

Incentive Management Admin Design Guide

316 PUBLIC Calculations Overview
23.3.3 Specifying Payee Pre-Assignments

Payee pre-assignment is an optional feature. If your transactions are pre-assigned to participants (payees),
positions, titles, or a combination of the three, you can create credit rules to filter transactions based on their
pre-assignment.

Additionally, if you have enabled generic attributes on transaction payee pre-assignments, you can use these
generic attributes in direct transaction credit rules. These generic attributes can be used, for example, to
specify a credit split for a shared transaction between one or more positions where each position is assigned its
own specific rate for the split.

Procedure

1. Choose Calculations > Transactions.

2. Search for the transaction or transactions to which to add payee pre-assignments if required.
3. Select the transaction.
4. Choose the Payee Pre-Assignment tab if required.
5. Choose Add in the detail panel. A new index number is automatically created.
Each index specifies a payee, position, or title or a combination of two or more of the three. The calculation
uses this information to identify each grouping of payee pre-assignment information. Use multiple indexes
to assign the same transaction to different combinations of participants, positions, and titles.
6. To specify the information to be used to determine who should receive credit for the transaction, do one or
all of the following:
• Specify a participant name in the Payee field. Although data is entered by participant name, the
system populates the Payee field with the participant ID when you navigate to another field, for
example, Position, or choose Save.
• Specify a position name in the Position field. Only positions that are associated with the same
processing unit as the transaction can be selected. .
• Specify a title name in the Titles field.
• If generic attributes for Transaction Payee Pre-assignments are enabled, you can add information in
the generic attribute fields for each index.

 Note

If the message ”r; Please enter a compensation date” displays when you are specifying information,
you must enter a compensation date for the associated transaction in the Transaction tab. You cannot
add payee pre-assignment information without a compensation date.

For example, if the credit for a transaction should be split across two or more positions, you can add an
indexed payee pre-assignment record for each position then specify the percentage split for each position
in a designated generic number field on each record.
7. Repeat Steps 5 and 6 to add additional indexes.
8. Choose Save.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 317
23.3.4 Modifying Transactions

To modify a transaction is to change a specific field that does not affect the transaction’s value. For example,
you can modify the comments on a transaction. Modifying a transaction sets it as runnable.

Procedure

1. Choose Calculations > Transactions.

2. Search for the transaction(s) you want to modify.
3. Select the transaction or transactions to be modified.
4. Choose the Transactions tab.
5. Change the appropriate fields in the detail pane.
6. Choose Save.

You can modify any field except the following:

• Order
• Line
• Subline
• Origin
• Value (to change this, you must select Adjust)
• Preadjusted Value
• Business Unit

When you modify any of the transaction fields, the system automatically resets the transaction’s runnable
status. This allows credits and other results data from the transaction to be recalculated when you next run
the calculation. The runnable attribute has a checkbox in the Transactions detail pane; after you modify any
transaction attribute, the system checks this box.

23.3.5 Removing a Payee Pre-Assignment

Payee pre-assignments must be manually removed from a transaction if the position, title, or payee to which
they refer is removed. If the association is not removed, a warning is generated by the calculation.

Procedure

1. Choose Calculations > Transactions

2. Search for the transaction from which the payee pre-assignment is to be removed.
3. Select the Transaction.
4. Choose the Payee Pre-Assignment tab.
5. Select the pre-assignment or pre-assignments to be removed.

Incentive Management Admin Design Guide

318 PUBLIC Calculations Overview
6. Choose Remove.
7. Choose Save to save the transaction.

23.3.6 Adjusting Transactions

When you adjust a transaction, the system creates an adjustment entry. If you make more than one adjustment
to a transaction, a separate record is created for each adjustment and the system updates the transaction
value accordingly. You might want to adjust a transaction if you find that an imported or manual transaction
has an error, such as an incorrect amount. When you adjust a transaction, the system automatically marks the
transaction as runnable so that it gets processed in the next calculation run.

Procedure

1. Choose Calculations > Transactions

2. Search for the transaction or transactions you want to adjust.
3. Select the transaction or transactions.
4. Choose Transactions tab.
5. Choose Adjust button located next to the Value field in the detail panel.
6. Perform the following in the Adjust dialog:
• Specify one of the following adjustment options:
• Adjust by - adjusts the transaction value by a percentage or a specific currency amount depending
on the unit type specified. To specify a unit type, click the Unit Type field button. For example, if the
original value is $100, Adjust by 10% sets the value to $110.
• • Adjust to - adjusts the transaction to an amount. To specify a currency unit type other than the
one assigned to the original transaction, click the Unit Type field button. For example, if the original
value is $100, Adjust to 200 sets the value to $200.
• Reset - to change the adjusted value back to the original value.
• If the administrator has created reason codes, you can select a code that indicates the reason for the
adjustment.
• (Optional) In the Comments field, enter text that describes the adjustment.
7. Choose Close to close the Adjust dialog.
8. Choose Adjust to save the adjusted transaction. The adjusted transaction is processed in the next
calculation run for the period in which the transaction’s compensation date occurs.

 Note

If you adjust the same transaction multiple times, do not mix adjustment types. For example, do not
switch between Adjust by and Adjust to types for the same transaction.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 319
23.3.7 Copying Transactions

You can copy any of the transactions shown in the summary pane and change any of the detail information
about the copy. Most commonly, you change the order and line numbers to copy the transaction to a different
order.

You can copy only one transaction at a time.

Procedure

1. Choose Calculations > Transactions

2. Search for the transaction to be copied.
3. Search for the transaction and select it in the Summary panel.
4. Choose Duplicate.
• The system copies the highlighted transaction and inserts it at the top.
• To change details for the copied transaction, edit the fields as needed. For example, to copy the
transaction to a different order, edit the Order and Line fields.
5. Choose Save.

23.3.8 Finding Objects Related to Transactions

You can find data related to one or more selected transactions by selecting the appropriate object option from
the Related pane.

Procedure

1. Choose Calculations > Transactions

2. Search for the transaction or transactions for which you want to find related objects.
3. Select the transaction or transactions for which you need to find related objects.
4. Select an object option, for example, Credits in the Related panel. f you are searching for products,
customers, postal codes or objects associated with user-defined classifier types, the objects are retrieved
immediately and the results are displayed in the related workspace. If no results are found, the message
“No Records Found”? is displayed. If you are searching for credits or orders, the Search For Related
Objects dialog displays with the name of the selected object substituted for the object name.

The available options and data returned are as follows:

• Credits—returns the credits referring to (or generated by) the selected transaction.
• Commissions—returns the commissions referring to (or generated by) the selected transaction.
• Orders—returns the orders referring to the selected transaction.

Incentive Management Admin Design Guide

320 PUBLIC Calculations Overview
• Product—returns the products referred to by the selected transactions that meet the classification rule
criteria of the product’s parent category hierarchy and have a compensation date within the specified
default period.
• Customer—returns the customers referred to by the selected transaction that meets the classification
rule criteria of the customer’s parent category hierarchy and has a compensation date within the specified
default period.
• Generic Classifiers—returns the objects referred to by the selected transactions that meet the
classification rule criteria of the generic classifier’s parent category hierarchy and have a compensation
date within the specified default period. Generic classifiers must be enabled to view this option.
• Postal Code—returns the postal codes referred to by the selected transactions that meet the classification
rule criteria of the postal code’s parent category hierarchy and have a compensation date within the
specified default period.

 Note

To search for pre-assigned transactions, use the Advanced Search window and search for Transaction.
Transaction Payee Pre-Assignments.* fields. These are Comp Date, Order, Payee ID, Position Name, Title
Name, and Generic Attributes (if enabled).

23.4 Credits Overview

Credit indicates an allocation of the value of a sales transaction or an entire order to a position assignment.
Credits are normally generated by credit rules, or they can be imported along with transaction data, or
manually entered in the system. You can transfer, modify, copy, or adjust credits from the Credits workspace.

When you create, modify, or adjust a credit, the system automatically marks its related transaction as
"runnable." When you next run the calculation in Incremental mode, the system reprocesses the transaction
and recalculates all credits related to the transaction including the modified or adjusted credit. In addition, you
can copy and transfer credits from one participant to another.

Related Articles

• Credits Workspace [page 322]

• Creating a Manual Credit [page 322]
• Transferring Credits [page 325]
• Modifying a Credit [page 327]
• Adjusting Credits [page 328]
• Copying Credits [page 329]
• Setting a Credit’s Release Date [page 330]
• Finding Objects Related to Credits [page 330]

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 321
23.4.1 Credits Workspace
Navigate to Calculations > Credits to access the Credits workspaces.

The Credits workspace can be viewed in list view.

The Custom attributes tab is displayed depending on whether or not the administrator has enabled custom
attributes for credits.

Credits Summary

You can view credits and create manual credits. You can transfer, modify, copy, or adjust credits from the
Credits Summary toolbar.

Credits Details

You can edit details in the General Information tab. From the Related Search icon, you can view the results data
that contributed to a selected credit, as well as results data to which the credit contributed. For example, in the
Source area on the left, the name of the source credit - along with the associated position, payee, and period
name - is displayed with the credit value. In the Contributing To area on the right, the names of the credits
contributed to and their values are displayed.

The Adjustments tab displays adjustments that have been made to a selected credit. For example, if the
adjustment was an adjustment to a specific value, the system displays adjust To in the Adjustment Type
column in the detail pane. (If the Adjustment Type column is not displayed, use the scroll bar in the detail
pane.) If the adjustment was by a percentage or a value, the system displays adjustBy.

23.4.2 Creating a Manual Credit

You can manually create a credit for a position assignment. For example, you might need to create a credit
for the participant currently assigned to a position if that participant would otherwise not receive credit for a

Incentive Management Admin Design Guide

322 PUBLIC Calculations Overview
particular sales activity by way of the plan assignment’s rules. You create a manual credit based on an order
and a transaction.

 Note

When you create the credit, it is updated in the system. However, the system does not process the credit
until the next time you run the calculation.

Prerequisites

When creating a manual credit for a position assignment, the following must be true:

• The position must have an associated participant (not an empty position).

• The end date of the Period specified for the credit should be greater than the transaction compensation
date. For example, if the Credit Period is January 2008, the transaction compensation date must be before
than February 1, 2008.
• If Custom Processing Dates are enabled:
• The compensation date for the credit must be within the processing effective dates (Is Processing dates)
of the position. If custom processing dates are not enabled, the system uses the effective dates of the
current version of the position.
• The compensation date for the credit can be outside of the receiving credit effective dates of the position.
However, the compensation date for the credit must still exist within the processing effective dates of the
position.

If you create a manual credit based on a prior period transaction, you should create it as a held credit with a
release date of the current period. A prior period credit would not be processed unless you run the period in
which its compensation date occurs. For non-held credits, this is the same as the transaction’s compensation
date. For held credits, this is the same as the release date.

Procedure

1. Navigate to Calculations > Credits.

2. Enter required values as indicated in the following table from the detail panel.
3. Choose Create and provide the following information:

Field Name Description

Transaction (Required) The transaction associated with the credit.

Period (Required) The period that contains the credit; use the
drop-down menus to select the type of calendar (on the
left) and the period (on the right). If the default period was
selected, this defaults to the current period. If a date was
selected, the period is empty.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 323
 Field Name Description

Order The order ID from which the credit originates.

Position (Required) The position that receives the credit. You can
assign the credit only to position assignments that are ef-
fective at the time of the credit’s compensation date. Only
positions that are associated with the same processing
unit as the transaction can be selected.

Orders always have a Processing Unit. If there is no Or-

der for a Business Unit, then the Order Processing Unit
= Unassigned. You cannot assign a position that has a
Processing Unit to an order that does not. The following
message is displayed: Order Processing Unit and Position
Processing Unit does not match..

Name A unique identifier for the credit. This is a text field.

Title The title associated with the position that receives the
credit.

Value (Required) The amount of the credit. You can choose the
Unit Type field to select a unit type.

Create Date For manual credits, defaults to the current date and is
not editable. For calculated credits, it indicates when the
credit was created by the calculation.

Credit Type Select a credit type to indicate the source of the credit.
The default credit types are commission, quota, order, and
revenue, but additional credit types can be created.

Preadjusted Value (Required) The credit’s value before any applicable adjust-
ments or modifications. The system completes this field.

Compensation Date The system completes this field. This is the credit’s com-
pensation date. This date determines in what period the
credit is processed. For a manual unheld credit, it is the
same date as the transaction’s Compensation Date. For a
manual held credit, this date is the same as the Release
Date.

Origin Type The system sets this field to report whether the credit was
calculated, imported, or manually created.

Rule Reports the associated credit rule, if any (displays for cal-
culated credits only).

Ever Held Indicates whether the credit should be held and works
with the Release Date.

Incentive Management Admin Design Guide

324 PUBLIC Calculations Overview
 Field Name Description

Release Date If Ever Held is enabled, you can specify a release date by
entering a date or selecting a date using the Calendar field
button. If the credit should be held indefinitely, the release
date is set to End Of Time.

This field can be used to find credits that were held, even
after they were released.

Is Rollable Check the box to specify that the credit can be rolled to
another position assignment.

Roll Date The date used to look up roll relationships in the relation-
ships hierarchy. This is usually the compensation date of
the associated transaction. You can enter a date or select
a date using the Calendar field button.

Reason Code A code that indicates the reason for the credit. Reason
codes must be created by the administrator.

Comments User-entered comments, if applicable.

Business Units (Read-only) The system automatically sets the business

unit on the credit to match the business unit assignment
on the position.

4. Choose Save. The system saves the manual credit and the next calculation run processes it.

23.4.3 Transferring Credits

You can transfer one or more transaction-level credits between positions assigned to participants. For example,
you might need to do this if one salesperson sold a product in another salesperson’s territory, and you must
manually give part of the credit for the sale to the original salesperson.

 Note

You cannot transfer order-level credits. An order-level credit is a credit that is generated by a credit rule
that has a source of order.

The system facilitates transferring credits from one participant to another by establishing audit trails for credit
transfers. Each time you transfer a percentage or value amount of a credit to a participant, the system creates
as an adjustment to the existing credit. The transferred item is stored as a new, manual credit. Transferring a
credit causes the transactions associated with both the original credit and the new credit to be considered as
runnable.

 Note

When you transfer the credit, the system updates the repository. However, the system does not process the
transferred credit until the next time you run the calculation.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 325
Procedure

1. To transfer a credit to another participant, navigate to Calculations > Credits.

2. Search for the credit to be transferred.
3. Select a credit in the Summary panel.
4. Choose Credit .
5. Choose Transfer, which is next to the Value field. The Transfer dialog displays.
6. Enter the following information in the Transfer dialog:

Operator Description

Amount
(Required) Enter a number, and click the Unit Type field
button to specify whether a percentage of compensation
or an exact monetary amount to compensation should be
transferred. For example, to transfer 10% of $100 credit,
enter 10 and select the percent unit type.

To
(Required) The name of the position or participant to
whom the credit should be transferred.

Period
Choose the payout period for the credit to transfer.

If you do not specify a period, the transferred credit is

assigned the same period as the source credit.

Credit Type
(Required) Select a credit type to indicate the type for the
transfer. The default credit types are commission, quota,
order, and revenue, but additional credit types can be cre-
ated.

Reason Code
A code that indicates the reason for the transfer. Reason
codes must be created by the administrator.

Rollable
Check the box to specify that the credit can be rolled to
another position assignment.

Roll Date
If you specify Rollable, select the date to roll the credit.

Comment Enter text that describes the credit transfer. Comments

are retained on both the newly created credit record and
the original credit.

7. (Optional) Choose Preview. The Preview Transfer dialog displays the original payee, transfer to payee, and
transfer value.
8. If the amount is correct, choose Accept then proceed to Step 9.
9. Choose OK in the Adjust dialog.

Incentive Management Admin Design Guide

326 PUBLIC Calculations Overview
10. Choose Save. The system saves the transferred credit to the Credits workspace.

23.4.4 Modifying a Credit

When you modify a credit, you change the record of the existing credit. The fields you can modify are limited
based whether the credit was calculated, imported, or manually entered.

 Note

When you modify the credit, the system updates the repository. However, the system does not process the
credit until the next time you run the calculation

Procedure

1. Navigate to Calculations > Credits.

2. Search for the credit to be modified.
3. Select the credit in the Summary pane and modify the following information as needed:

Field Description

Name A unique name for the credit. Only editable for manual and
imported credits.

Credit Type Indicates the source of the credit. The default credit types
are commission, quota, order, and revenue, but additional
credit types can be created. Only editable for manual and
imported credits.

Ever Held Indicates whether the credit should be held and works
with the Release Date. This option can be modified for
imported and manual credits, but not calculated credits.

Release Date If Ever Held is enabled, you can specify a release date
by entering a date or selecting a date using the Calendar
field button. If the credit should be held indefinitely, leave
release date blank. The release date is set to End Of Time.

Is Rollable Indicates that the credit can be rolled to another position

assignment. This field is editable for manual and imported
credits, but is read only for calculated credits.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 327
 Field Description

Roll Date If Is Rollable Credit is enable, this is the date the system
uses to look up roll relationships in the relationships hier-
archy. This is usually the compensation date of the associ-
ated transaction.

Comments (Optional) Comments about the credit.

Reason Code (Optional) A code that indicates the reason for the credit.
Reason codes must be created by the administrator.

4. If the administrator has enabled custom attributes for credits, the Custom attributes sections is visible in
general information tab to edit values in those fields.
5. Choose Save.

23.4.5 Adjusting Credits

When you adjust credits, the system creates an adjustment entry. If you make more than one adjustment to a
credit, a separate record is created for each adjustment and the system updates the credit value accordingly.

 Note

When you adjust the credit, the system updates the repository. However, the system does not process the
adjusted credit until the next time you run the calculation

If you are adjusting a calculated credit and Custom Processing Dates are enabled for the position that the
credit is to be applied to, the Compensation Date is compared to the Processing End Date for the Position
when you save the adjustment. In most instances, you cannot save a credit adjustment if the Processing
End Date is less than or equal to Compensation Date. However, if there is an indefinite hold on the credit,
the Compensation Date is set internally to End of Time and the credit can be saved regardless of Custom
Processing Dates for the position.

Procedure

1. Navigate to Calculations > Credits.

2. Search for the credit or credits to be adjusted.
3. Select the credit or credits in the Summary panel.
4. Choose Credit if required.
5. Choose Adjust next to the Value field in the detail panel.
6. Perform the following in the Adjust dialog:
• Specify one of the following adjustment options:
• Adjust by - adjusts the credit value by a percentage or a specific value amount depending on the unit
type specified. To specify a unit type, choose the Unit Type button.

Incentive Management Admin Design Guide

328 PUBLIC Calculations Overview
7. Enter a negative number to decrease a credits' value.
8. Enter a positive number to increase the credit’s value.
• Adjust to - adjusts the credit to an amount. To specify a unit type other than the one assigned to the
original credit, choose the Unit Type button.
• Reset - to change the adjusted value back to the original value.

 Note

If you adjust a credit more than once, be sure that all adjustments use the same method (such as
by value or by percentage, not both). Otherwise, the system uses only the last adjustment type. For
example, if you adjust a $100 credit by $50 (adjusted credit value = $150) and then adjust the credit by
10% (theoretically, the adjusted credit value is $165), the system would process the credit during the
next calculation using only the last adjustment method (the 10% adjustment, adjusted credit value =
$110)

• (Optional) If the administrator created reason codes, you can select a code that indicates the reason
for the credit.
• (Optional) Enter text that describes the credit adjustment.
9. Choose Cancel in to close the Adjust dialog.
10. Choose Adjust to save the adjusted credit. The adjustment is processed in the next calculation run for the
period in which the credit’s compensation date occurs.

23.4.6 Copying Credits

You can copy transaction-level credits shown in the summary pane and change any of the detail information
about the copy. Most commonly, you change the participant to whom the credit applies. You cannot copy
order-level credits. An order-level credit is a credit that is generated by a credit rule that has a source of order.
Copying a credit causes the transaction associated with the new credit to be considered as runnable.

When you copy credits, the system is updated immediately. However, the copied credit is not processed until
the next time you run the calculation.

Procedure

1. Navigate to Calculations > Credits.

2. Search for the credit to be copied.
3. Select Credit in the Summary panel.
4. Choose Duplicate in the Ellipsis Menu (…).
5. Edit the specific fields in the detail panel for the copied credit. For example, to copy the credit to a different
position, edit the Position field.
6. Choose Save.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 329
23.4.7 Setting a Credit’s Release Date

You can manually set the release date of a held credit. You can set or change the release date of a held credit
regardless of whether it is a calculated, an imported, or a manual credit. You can either indicate a specific
release date, or choose to have the credit held indefinitely. The credit is processed in the period of the release
date.

To hold a credit indefinitely, do not specify a release date. The system considers the credit compensation date
to be the End Of Time. You can also specify a release date in the credit rule that generates the credit.

 Note

The calculation generates an error when it goes to process a released credit for a position or payee that is
not effective at the time that the credit is being released.

An item that is held with an offset has a release date of the end date of the applicable, offset period.

 Note

For Administrators: credits that are held continue to have isHeld=1 after processing. The isHeld attribute
(the Ever Held field) indicates if the credit has been held at any point in time and if the hold is still valid, even
if the hold is not still effective (the release date is in the past).

Procedure

1. Choose Credit from the Calculation tab.

2. Search for the credits to be released.
3. Select Credit in the Summary panel.
4. Select the Credits tab.
5. Perform the following in the release date field next to the ever held option:
• To hold the credit until a specific date, enter a date or choose the Calendar field button to select a date.
• To hold the credit indefinitely, leave the release date field blank. The credit compensation date is set to
End Of Time.
6. Choose Save.

23.4.8 Finding Objects Related to Credits

You can find data related to one or more credits by selecting the appropriate object option from the Related
pane. The available options and the data returned are as follows:

• Rules—returns the rules referred to by the credit.

• Positions—returns the positions referred to by the selected credit.
• Participants—returns the participants referred to by the selected credit.
• Orders—returns the orders referred to by the selected credit.

Incentive Management Admin Design Guide

330 PUBLIC Calculations Overview
• Transactions—returns the transactions referred to by the selected credit.
• Source Credits—returns the credits that generated the selected credit.
• Target Credits—returns the credits generated by the selected credit.
• Commissions—returns the commissions generated by the selected credit.
• Measurements—returns the measurements generated by the selected credit.

To find objects related to credits:

1. Click Credits from the Results tab.

2. Search for the credit or credits for which you want to find related objects.
3. Select the credit or credits in the Summary panel.
4. Select an object option in the Related panel, for example, Orders.

• If you are searching for related rules, the results are immediately retrieved and displayed in the Rules
Wizard workspace. If no results are found, the message No results found is displayed.
• If you are searching for an object other than rules, the Search For Related Objects dialog displays with the
name of the selected object substituted for the object name.

23.5 Measurements Overview

Measurements are generated by measurement rules and are based on credits or other calculations. There are
two kinds of measurement rules and hence measurements: primary and secondary.

A measurement rule that calculates an aggregate of credits generates a primary measurement; a

measurement rule that calculates an aggregate of measurements generates a secondary measurement.

Related Information

• Measurements Workspace [page 331]

• Finding Objects Related to Measurements [page 332]

23.5.1 Measurements Workspace

After you run the calculation, the Measurements workspace displays both primary and secondary named
measurements.

Navigate to Calculations > Measurements to access the Measurements workspaces.

After you run the calculation, the Measurements workspace displays both primary and secondary named
measurements. Details are displayed in the Measurement Summary and General Information tab.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 331
23.5.2 Finding Objects Related to Measurements

You can find data related to one or more measurements by selecting the appropriate object option from the
Related pane.

Procedure

1. Navigate to Calculations > Measurements.

2. Search for the measurement or measurements for which you want to find related objects.
3. Select the measurement or measurements in the Summary panel.
4. Select an object option in the Related panel, for example, Credits.

• If you are searching for related rules, the results are immediately retrieved and displayed in the RulesWizard
workspace. If no results are found, the message “No results found” is displayed. Rule searches use
NamedQuery and don’t display a Simple Search dialog, which is why the Note above was added. All other
objects use LegalMoveDynamicQuery, which brings up the Simple Search dialog
• If you are searching for an object other than rules, the Search For Related Objects dialog displays with the
name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Positions—returns the positions referred to by the measurement.

• Participants—returns the participants referred to by the measurement.
• Credits—returns the credits that generated the measurement.
• Incentives—returns the incentives generated by the measurement.
• Commissions—returns the commissions generated by the measurement.
• Deposits—returns the deposits generated by the Measurements.

Incentive Management Admin Design Guide

332 PUBLIC Calculations Overview
• Source Measurements—returns the measurements that generated the selected measurement.
• Target Measurements—returns the measurements generated by the selected measurement.
• Rules—returns the rules referred to by the measurement.

23.6 Incentives Overview

An incentive is the result of comparing measurements or credits to targets. An incentive is the output of an
incentive rule, which calculates commissions or bonuses for a position assignment.

The input to each incentive rule is a measurement, another incentive, or a formula. The output of an incentive
rule is a named incentive of specific value. The incentive is available for deposit for a position assignment for a
specified period. The system compares performance measurements with targets for each position assignment
assigned to a plan. In the Reward stage of the calculation, rate tables and other formulas are applied to
the measurements. During this stage, the system uses incentive rules to calculate incentive earnings that
correspond to the performance level achieved.

 Note

You can choose whether or not to include per-credit commission detail in your incentives. If you choose to
include this detail, calculation performance might be affected.

Related Articles

• Incentives Workspace [page 333]

• Finding Objects Related to Incentives [page 334]

23.6.1 Incentives Workspace

In the Incentives workspace, you can view incentives and objects related to those incentives.

Navigate to Calculations > Incentives to access the Incentives workspaces.

After you run the calculation, the system displays the output of all the commission and bonus rules in the
Incentives workspace.

If the administrator has enabled custom attributes section, then the custom attributes section is visible in the
General Information tab for the incentives and you can enter and modify values for these attributes.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 333
23.6.2 Finding Objects Related to Incentives

You can find data related to incentives by selecting the appropriate object option from the Related pane.

Procedure

1. Navigate to Calculations > Incentives.

2. Search for the incentive or incentives for which to find related data.
3. Select the incentive or incentives for which you want to find related objects.
4. Select an object option n the Related panel, for example.

• If you are searching for related rules, the results are immediately retrieved and displayed in the Rules
Wizard workspace. If no results are found, the message “No results found” is displayed. Rule searches use
NamedQuery and don’t display a Simple Search dialog, which is why the Note above was added. All other
objects use LegalMoveDynamicQuery, which brings up the Simple Search dialog.
• If you are searching for an object other than rules, the Search For Related Objects dialog displays with the
name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Positions—returns the positions referred to by the selected incentive.

• Participants—returns the participants referred to by the selected incentive.
• Commissions—returns the commissions that generated the selected Incentive.
• Measurements—returns the measurements that generated the selected incentive.
• Deposits—returns the deposits generated by the selected incentive.
• Source Incentives—returns the incentives that generated the selected incentive.
• Target Incentives—returns the incentives generated by the selected incentive.
• Rules—returns the rules referred to by the selected incentive.

Incentive Management Admin Design Guide

334 PUBLIC Calculations Overview
23.7 Commissions Overview

A commission is a kind of incentive award that is based on credited transactions or other measurement values,
and is usually proportional to the value of the measurement. Commission rules determine commission values.

 Note

The output of a commission rule is commission objects and an incentive object; the incentive object is the
aggregate value of all commissions generated by the rule.

23.7.1 Commissions Workspace

Navigate to Calculations > Commissions to access the Commissions workspaces.

After you run the calculation, Commissions displays the output of all commission rules in the Commissions
workspace.

The Commissions workspace is used for research and reporting purposes only.

23.7.2 Finding Objects Related to Commissions

You can find data related to one or more commissions by selecting the appropriate object option from the
Related pane.

Procedure

1. Calculations > Commissions.

2. Search for a commission or commission for which you want to find related data.
3. Select commission or commissions In the Summary panel.
4. Select an object option, such as Credits in the Related panel.

• If you are searching for related rules, the results are immediately retrieved and displayed in the Rules
Wizard workspace. If no results are found, the message “No results found is displayed.
• If you are searching for an object other than rules, the Search For Related Object dialog displays with the
name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Positions—returns the position referred to by the selected commission.

• Participants—returns the participant referred to by the selected commission.
• Credits—returns the credits that generated the selected commission.
• Measurements—returns the measurements that generated the selected commission.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 335
• Incentives—returns the incentives generated by the selected commission.
• Deposits—returns the deposits generated by the selected commission.
• Transactions—returns the transactions generated by the selected commission.
• Titles —returns the titles generated by the selected commission.
• Rules—returns the rules referred to by the selected commission

23.8 About Deposits

Deposits are generated by deposit rules, or they can be imported, or they can be manually entered.

Deposit rules determine how much of each kind of incentive compensation a position assignment has earned
and when the compensation can be paid. Deposits can also be imported.

Related Articles

• Deposits Workspace [page 336]

• Adjusting Deposits [page 337]
• Modifying a Deposit [page 337]

23.8.1 Deposits Workspace

Navigate to Calculations > Deposits to access the Deposits workspaces.

The Custom attributes tab is displayed depending on whether or not the administrator has enabled custom
attributes for deposits.

Deposits Summary

The Deposits workspace lets you see and adjust deposits, which represent amounts to be paid to each position
assignment processed in the associated deposit rule.

Deposits Details

You can edit details in the General Information tab. From the Deposit tab you can enter and modify deposit
information, adjust deposits, and view deposit information for a deposit or deposits selected in the summary
pane.

Incentive Management Admin Design Guide

336 PUBLIC Calculations Overview
The Adjustments tab displays adjustments that have been made to a selected deposit. For example, if the
adjustment was an adjustment to a specific value, the system adjust to in the Adjustment Type column in
the detail pane. (If the Adjustment Type column is not displayed, use the scroll bar in the detail pane.) If the
adjustment was by a percentage or value, the system displays adjust By.

23.8.2 Adjusting Deposits

When you adjust deposits, the system creates an adjustment entry. If you make more than one adjustment
to a deposit, a separate record is created for each adjustment and the system updates the deposit value
accordingly.

Adjusted deposits can be viewed from the Adjustment tab of the Deposits workspace.

Procedure

1. Navigate to Calculations > Deposits.

2. Search for the deposit or deposits to be adjusted.
3. Select the deposit or deposits in the Summary panel.
4. Choose the Deposit tab.
5. Choose Adjust located next to the Value field in the detail panel specify one of the following adjustment
options:
• Adjust by - adjusts the deposit value by a percentage or a specific value amount depending on the unit
type specified. To specify a unit type, choose the Unit Type button. To decrease a deposit’s value, enter
a negative number. To increase the deposit’s value, enter a positive number.
• Adjust to - adjusts the deposit to an amount. To specify a value unit type other than the one assigned
to the original deposit, choose the Unit Type button.
• Reset - to change the adjusted value back to the original value.
• If the administrator has created reason codes, you can select a code that indicates the reason for the
adjustment.
• (Optional) Enter text that describes the adjustment.
6. Choose Cancel to close the Adjust dialog.
7. Choose Adjust to save the adjusted deposit. The adjustment is processed in the next calculation run for the
period in which the deposit occurs.

23.8.3 Modifying a Deposit

You can make various changes to the deposit details in the detail pane. If you modify a deposit, calculation
reapplies the adjustment to the calculated deposit.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 337
Procedure

1. Navigate to Calculations > Deposits.

2. Search for the deposit or deposits to be modified if necessary.
3. Select the deposit or deposits in the Summary panel.
4. Choose the General Information tab if necessary.
5. You can modify field values as noted in the following table in the Detailspane.

Field Description

Period The period that contains the deposit and the calendar within that period. Only editable for
manual and imported deposits

Name A unique name for the deposit. Only editable for manual and imported deposits.

Earning Group Groups similar types of deposits. Positive and negative balances within an earning group are
offset against each other. Earning groups can be entered using the following methods:

• Type a text string into the field. For example, enter ”r;special incentives” to dynamically
create a special incentives earning group. Earning groups entered by this method are
not available to deposit rules or other deposits.
• Select an earning group from the drop-down list. Earning groups can be created in the
Earning Groups workspace. Earning groups added in the Earning Groups workspace are
available for all deposit rules and deposits.

Earning Code A code that differentiates deposits within an earning group. These codes help external
accounting systems track departmental earnings. Earning codes can be entered using the
same methods as earning groups.

Deposit Date (Optional) The date the deposit was created. For calculated deposits, this is the calculation
run date.

Ever Held When enabled, that the deposit is to be held and works in conjunction with the Release
Date. If you modify the Ever Held option and Release Date for a deposit related to a posted
payment, you must rerun the calculation for the period to generate a negative applied
deposit (earnings) so that the payment is not made twice.

Release Date If Ever Held is enabled, a date in this field indicates when the deposit should be released. If
Ever Held is enabled and the Release Date is blank, the deposit is held indefinitely.

Reason Code A code that indicates the reason for the deposit. Reason codes must be created by the
administrator.

Comments A description or comments about the deposit.

6. Choose Save.

Incentive Management Admin Design Guide

338 PUBLIC Calculations Overview
23.8.3.1 Holding a Deposit

Deposits can be held until a specific date or indefinitely.

Procedure

1. Navigate to Calculations > Deposits.

2. Search for the deposits to be placed on hold.
3. In the detail pane, enable the Ever Held option.
4. To hold the deposit until a specific date, enter a date or choose the Calendar to select a date. To hold the
deposit indefinitely, leave the release date blank.
5. Choose Save.

 Note

If you modify the Ever Held option and Release Date for a deposit related to a posted payment, you must
rerun the calculation for the period to generate a negative applied deposit (earnings) so that the payment is
not made twice.

23.8.3.2 Creating a Manual Deposit

You can award a deposit to a position assignment where the deposit is not directly related to the standard rule
processing. After creating a manual deposit, the system processes the manual deposit the next time that you
run the calculation.

Also, manual deposits are not reset during calculation processing. If Custom Processing Dates are enabled,
at least one day of the Period specified for the deposit must be within the Is Processing start and end dates
for the current version of the position. For example, if the Is Processing effective dates are February 2008 to
June 2008, the Period for the deposit cannot be January 2008. If you award a manual deposit to a position
assignment and the version of the position changes (such as for a change in payee), you must delete the old
manual deposit and create a new one for the new position version.

Procedure

1. Navigate to Calculations > Deposits.

2. Choose Create.
3. Choose the General Information tab.
4. If the deposit should exist within a period and effective dates other than the default, select the appropriate
calendar and period.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 339
  Note

You must create the deposit to be effective during the time when the position assignment (position /
payee combination) is also effective. The system does not allow you to create a manual deposit for a
time period when the specified position assignment is not effective.

5. Enter the remaining values for the deposit.

Field Name Description

Name (Required) A unique name for the deposit.

Position (Required) The name of the position associated with the deposit.

Title (Read only) The title associated with the position.

Create Date For manual deposits, defaults to the current date and is not editable.

Origin Type Defaults to Manual, Calculated, or Imported depending how the deposit was created. This field
is not editable.

Earning Group Groups similar types of deposits. Positive and negative balances within an earning group are
offset against each other. Earning groups can be entered using the following methods:

• Type a text string into the field. For example, enter ”r;special incentives” to dynamically
create a special incentives earning group. Earning groups entered by this method are not
available to deposit rules and other deposits.
• Select an earning group from the drop-down list. Earning groups can be created in the
Earning Groups workspace. Earning groups added in the Earning Groups workspace are
available for all deposit rules and other deposits.

Earning Code A code that differentiates deposits within an earning group. Earning codes help external ac-
counting systems track departmental earnings. Earning codes can be entered using the same
methods as earning groups.

Rule For calculated deposits, this field displays the deposit rule that generated this deposit. This field
is not applicable to manually created deposits.

Preadjusted Value (Read only) The deposit’s value before any applicable adjustments or modifications. When
creating a manual deposit, the Preadjusted Value and Value are the same and entering the
Value updates this field.

Value (Required) The value of the deposit. Choose the Unit Type button to select a unit type. The
options are currency, percent, quantity, and integer.

Deposit Date You can specify any date in this field.

Ever Held Indicates that the deposit is to be held and works in conjunction with the Release Date.

Release Date If Ever Held is enabled, a date in this field indicates when the deposit should be released. If Ever
Held is enabled and the Release Date is blank, the deposit is held indefinitely.

Incentive Management Admin Design Guide

340 PUBLIC Calculations Overview
 Field Name Description

Reason A code that indicates the reason for the deposit. Reason codes must be created by the adminis-
trator.

Comments Enter a description or comments about the deposit.

Business Units (Read only) The system automatically sets the business unit on the deposit to match the
business unit assignment on the position.

6. Choose Save.

23.8.3.3 Setting a Deposit’s Release Date

You can manually set the release date of a held deposit. You can set or change the release date of a deposit
regardless of whether it is a calculated, an imported, or a manual deposit. You can either indicate a specific
release date, or choose to have the deposit held indefinitely. The calculation processes all deposits released
within the period.

 Note

The calculation generates an error when it goes to process a released deposit for a position or payee that is
not effective at the time that the deposit is being released.

Procedure

1. Navigate to Calculations > Deposits.

2. Search for the deposit or deposits to set a release date for.
3. Select the deposit or deposits that you want to set a release date for in the Summary panel.
4. Choose the General Information tab.
5. Perform the following in the date field next to the Ever Held option:
• To hold the deposit until a specific date, enter a date or choose the Calendar button to select a date.
• To hold the deposit indefinitely, leave the release date field blank.
6. Choose Save.

23.8.3.4 Finding Objects Related to Deposits

You can find data related to one or more deposits by selecting the appropriate object option from the Related
pane.

Incentive Management Admin Design Guide

Calculations Overview PUBLIC 341
Procedure

1. Navigate to Calculations > Deposits.

2. Search the deposits for which to find related objects.
3. Select the deposits in the Summary panel.
4. Select an object option in the Related panel, for example, Position. If you are searching for related rules or
payments, the objects are retrieved immediately and the results are displayed in the related workspace.
If no results are found, the message “No records found” message is displayed in summary view panel. In
case, you are searching for an object other than rules or payments, the Search For Related Objects dialog
displays with the name of the selected object substituted for the object name.

The available options and the data returned are as follows:

• Positions—returns the positions referred to by the selected deposit.

• Participants—returns the participants referred to by the selected deposit.
• Rules—returns the rules referred to by the selected deposit.
• Measurements—returns the measurements that generated the selected deposit.
• Commissions—returns the commissions that generated the selected deposit.
• Incentives—returns the incentives that generated the selected deposit.
• Payments—returns the payments generated by the selected deposit.
• Titles —returns the titles generated by the selected deposit.

Incentive Management Admin Design Guide

342 PUBLIC Calculations Overview
24 Payments and Balances Overview

Payments represent the incremental deposit amount to be paid for a specified fiscal period. Balances are
payment amounts generated for finalized periods.

Payments are always generated per position assignment within an earning group except when the Consolidate
Payee Payments preference is enabled. When this preference is enabled, payments are generated per payee
regardless of the position that the payee is assigned to.

24.1 Payments Workspace

Navigate to Calculations > Payments to access the Payments workspaces.

Payment Summary

The Payments workspace displays a summary of all the payments and balances calculated by the system for
position assignments when you ran the calculation. In the Summary view of the Payments workspace, the
system lists an aggregate payment summary item for each position assignment, period, earning group, unit
type, and business unit combination.

Payment Details

The following figure shows the General Information tab. From this tab, you can view the individual payment
and balance items that make up the payment summary item and view additional information about each of
these items. For each payment or balance item, the system lists the earnings that constituted the payment or
balance object. Information on the tab includes:

• Payment summary item: An aggregate value of all payments for a position assignment period, earning
group, unit type, and business unit. The unit type used and displayed is derived from the source deposit.
• The first line or lines for a payment or balance item lists the earnings calculated.
• The last line for a payment of balance item lists the payment or balance generated.

You can drag the column boundaries to customize the display.

The details for each line item on the General Information tab includes information for:

• Description—Lists the period description. For the last line for the earnings item, Payment or Balance is
shown to indicate the type of object.
• Earning Code—Displays the earning code for the payment or balance.

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 343
• Value—Displays the value for the payment or balance.
• Posted Date—Lists the date of the calculation run that posted the object. If an item is not posted, it is in
trial status.
• Finalized—Indicates a Yes if the position is finalized for the specified period, or if the period itself is
finalized.

 Note

A zero value payment is a valid payment, and gets created and posted just as any other payment does.

Here is an example of what a participant’s payment summary looks like in the Week 6 2015(February 2015)
period, after Compensate and Pay stages have been run. The participant has some trial payments and a couple
of prior period balances.

The figure shows that:

• Payments are calculated for February 2015, but they have not yet been posted. Because the payments are
in trial status, the balances included in these payments are not yet marked applied.
• A balance was generated and posted in November 2015 (a finalized period).

 Note

You can determine when payment summaries should be generated by setting one or more of the
following Generate Payment Summaries calculation preferences: After Calculating Payments, After Posting
Payments, After Finalizing Payments.

After running the calculation Post-stage, the payments are now posted, and the prior period balances are
marked as applied. The figure shows that:

• Payments are calculated and posted for November 2015. Because the payments are posted, the prior
period balances included in those payments are now marked applied.
• A balance was generated and posted in November 2015 (a finalized period).

After posting payments in the December 2007 period, the November 2015 payment summary displays the
posted and applied status of the balances brought forward into the December payments.

Incentive Management Admin Design Guide

344 PUBLIC Payments and Balances Overview
The figure shows that after posting payments in December 2007, the November balances show as applied
when looking at the November 2007 payment detail.

The following figure shows the Supporting Details tab. To see each type of result data, select the corresponding
check box in the Show area.

Additionally, if you change a field on a transaction that does not affect the value when viewing the transaction in
the detail pane of the Supporting Details tab, the system displays ”r;not a value adjustment” to help clarify the
kind of adjustment.

24.2 Negative Payments

You can configure the system to store payments that are negative amount using the Allow Negative Payments
preference. A negative payment might occur, for example, if a participant has a de-booking in a prior period that
results in a negative deposit balance that is larger than the payment for the current period. If the system is not
configured to allow negative payments, the payment is instead converted to a negative balance and is carried
forward to subsequent periods until it is balanced against the positive deposits for a period. If you have not
configured to allow negative payments and there is a negative balance from a previous period that is larger than
the payment for the current period, then no payment is posted in the Post stage. In this case, in the Finalize
stage the system generates the amount as an additional balance.

For example, if Tom Jones has a balance of -$100 from January and his February earnings are $75, the
calculation would result in a payment of -$25. However, because negative payments are not allowed, there is no

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 345
payment. Instead, when the Finalize stage is run for the February period, the system generates a $75 balance.
(You would not see the prior period balance in the February period until after the balance has been applied.)
The January balance is not applied until there are sufficient current period earnings to absorb the negative
prior period balance.

 Note

You can do a search for balances from previous periods to find the prior period negative balances .

Earning Groups and Codes in the Pay Stage

In general, the system generates a separate payment for each unique combination of an earning group and
earning code. Sometimes, some balancing is necessary across earning codes. The system attempts to balance
any negative payments within each earning group. Within each earning group, you can define a set of earning
codes. For example, for a Commission earning group, you can create an earning code for Sales Revenue
Commission, and one for Sales Booked Revenue Incentive. Each deposit originating from the sale of one of
these products is tagged with the appropriate earning code by the deposit rule in the Reward stage. Payments
derived from these deposits are also tagged with the earning code. For example, the result at the end of the
Pay stage might be a $200 payment to John Jones for his sales of Sales Revenue Commission, and a $100
payment for his sales of Sales Booked Revenue Incentive.

However, under certain circumstances, a payment labeled with an earning code might not reflect the amount
of deposits for that earning code. John Jones might have sold enough Sales Booked Revenue Incentive that he
expects a payment of $500, yet only receives $300. If this occurs, it could be the result of balancing payments
across earning codes, which occurs in the Pay stage of the calculation.

Finding Objects Related to Payments

You can find data related to one or more payments by selecting the appropriate object option from the Related
pane.

Procedure

1. Navigate to Calculations > Payments.

2. Search for the payment or payments for which you want to find related data.
3. Select an object option, for example, Deposits in the Related panel.

If you are searching for related deposits, the objects are retrieved immediately and the results are displayed
in the related workspace. If no results are found, the message “No Records Found” message is displayed in
Summary view panel. Deposit searches use NamedQuery and don't display a Simple Search dialog.. All other
objects use LegalMoveDynamicQuery, which display the Simple Search dialog.

If you are searching for related participants or positions, the Search For Related Object dialog displays with the
name of the selected object substituted for the object name.

Incentive Management Admin Design Guide

346 PUBLIC Payments and Balances Overview
The available options and the data returned are as follows:

• Participants—returns the participants referred to by the selected payment

• Positions—returns the positions referred to by the selected payment
• Deposits—returns the deposits referred to by the selected payment

24.3 Grouping and Balancing Overview

Earning groups and earning codes are used to group deposits, earnings, and payments. You use earning
groups to differentiate these items for the purpose of balancing certain groups of deposits during calculation
processing. You use earning codes as a more granular level within earning groups to label deposits for
accounting purposes (tracking of deposits by an external system).

Before you create deposit rules, consider how you need to handle balances. For example, if you have a separate
commission and bonus incentive rules, do you need output from these rules to be balanced together or
separately in your deposit rules for the same plan? If you need to balance the output separately, create earning
groups; if you need to differentiate between types of commissions, you could create earning codes. Create
earning groups and earning codes in the system first, then create the appropriate deposit rules.

If you are using different unit types for multiple currencies, such as one for US dollars and another for Euros,
grouping by unit type as well as by earning group and earning code is also done.

Related Articles

• Earning Groups [page 347]

• Earning Code [page 348]
• Multiple Currencies [page 348]

24.3.1 Earning Groups

When you create a deposit rule, you can assign the deposits it creates to different earning groups. Deposits
assigned to different earning groups are balanced separately (earning groups are also used for reporting
purposes). You might choose to do this, for example, if you need to balance commissions against commissions,
and bonuses against bonuses. If your business does not require the separation of deposits by earning groups,
assign all deposits to a single earning group.

You create an earning group by simply assigning it an identifying name and a description. The name is then
available from the Rules Wizard workspace when you create a Deposit rule. You can specify that the deposits
that it creates are assigned to an earning group. The following figure shows a conceptual view of when earning
groups are used during calculation processing.

During the Reward stage of the calculation, each deposit created by a Deposit rule is tagged with the earning
group specified by the rule. During the Pay stage, deposits are balanced to create one payment or balance for
each earning group. Any balances carried forward from previous periods are also included in the payment.

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 347
24.3.2 Earning Codes

Earning codes are labels that you can apply to deposit earnings for use in tracking payments according to your
business needs. The earning code totals are often exported to external accounting systems. When you create
deposit rules, you can elect to label the incentives the rule creates with earning codes.

For example, if a company needs to track all the commission earnings together, assign an earning code (for
example, EC-1) to the Commission Earning Group. If the company also needs to track bonuses, such as trips,
that are given as incentives, create an additional earning code (for example, EC-2) to apply to trip award
bonuses. Each earning code is tracked separately in the system.

24.3.3 Multiple Currencies

If you are using different unit types for multiple currencies, such as one for US dollars and another for Euros,
grouping by unit type as well as by earning group and earning code is done. For example, consider the data in
the following table.

Grouping by Multiple Currencies

Payee Earning Group Earning Code Unit Type Amount

Payee 1 Bonus Commission USD 1000

Payee 1 Bonus MBO USD -200 (balance)

Payee 1 Bonus Bonus Euro -600

In this example, all the payments and balances are within the same earning group; however, the negative
balance of -$200 is offset against the $1000 because they share the same unit type.

24.4 Earning Code Balancing

In some circumstances, a payment marked with an earning code within an earning group might not match
the earnings calculated for that earning code/earning group combination. For example, a position could be
awarded the following earnings items during the Pay stage, where earnings and payments are calculated.
These are both within the Revenue earning group:

• Sales Revenue Commission: $400

• Sales Booked Revenue Commission: $100

If these are the only items going into a payment, the payee assigned to the position would receive a payment
of $500 associated with the Revenue earning group. However, under certain circumstances, a payment labeled
with an earning code might not reflect the amount of deposits for that earning code. If this occurs, it might be
the result of balancing payments across earning codes, which occurs in the Pay stage.

Incentive Management Admin Design Guide

348 PUBLIC Payments and Balances Overview
For example, the earnings generated for the Revenue earning group for the position might be $500, but
the payment is only $300. The system balances earnings across earning codes only in the following
circumstances:

• A trial payment is negative.

• The system is configured to not allow negative payments. (This is the default setting.)

If negative payments are allowed, then payments are recorded as is. There is no need to balance out a negative
payment.

• The position is not finalized.

If the position is finalized, then the calculation does not calculate payments, only balances.

• The earning group has more than one earning code.

Within an earning group, if there are earnings for only one earning code and its payment is negative, it is
handled the same as any negative payment (converted to a negative balance in the Finalize stage and used in
calculations of payments for the earning group in subsequent periods). Consider the earlier example, but one
of the earnings items is negative (this resulted from a de-booking in a previous period):

• Sales Revenue Commission earning code: $400

• Sales Booked Revenue Commission earning code: -$300

Rather than carry forward a negative balance for the Sales Booked Revenue Commission through to some
future period when the payee generates enough revenue to offset it, the negative earnings from the one earning
code is subtracted from the position earnings in the other earning code earnings within the same earning
group. The system balances the -$300 earnings with the $400 earnings to generate a payment of $100. This
payment is marked with the Sales Revenue Commission earning code.

 Note

If there are no payments for the current period in a particular earning group, any negative balances from
prior periods for that earning group continue to be carried forward.

The system balances earnings and prior period balances across earning codes as follows: Prior period balances
are ordered by create date, with the earliest first. Current period earnings (applied deposits) are ordered by
value, with the smallest first. The earliest negative balance is subtracted from the smallest earnings item. Any
remainder is subtracted from the next smallest earnings, and so on. Negative payments and balances are
calculated across all earning codes within an earning group. For example, suppose there are three earnings
items with different earnings codes for a position assignment and for the Revenue earning group:

• Sales Revenue Commission earning code: -$200 prior period balance (this is the earliest balance)
• Sales Booked Revenue Incentive earning code: -$100 prior period balance
• Sales Management Total Revenue Bonus earning code: $50 current period earnings

After running Compensate and Pay, the -$100 balance from the prior period for the Sales Booked Revenue
Incentive earning code remains as a balance. The balance of -$200 for the Sales Revenue Commission also
remains. After the period is finalized, the $50 amount is created as a balance to be brought forward into
the next non-finalized period. No payment is generated because the total for the Revenue earning group is
negative.

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 349
24.5 Consolidating Payee Payments Overview

If some participants in your organization are assigned to more than one position, you can configure the system
to generate a single payment (or balance) for the participant by enabling the Consolidate Payee Payments
preference. If enabled, this feature generates a single payment for each earning group, earning code, unit type,
and participant, regardless of the number of positions that the participant is assigned to. If this feature is not
enabled, the system continues to generate a payment (or balance) for each participant, position, unit type,
earning code, and earning group combination.

Related Information

• Enabling Payee Payment Consolidation [page 350]

• About Payee Payment Consolidation [page 350]

24.5.1 Enabling Payee Payment Consolidation

After you enable Consolidate Payee Payments, it is advised that you not disable it. If you must do so, disable it
at the end of a period and after all balances have been reconciled. Be sure to note the following when enabling
payee payment consolidation:

• When you run the calculation for a subset of positions, be sure to do so for all positions held by a
participant. Otherwise, the calculation results data will be incorrect.
• Business unit security might be compromised in situations where a participant holds positions in separate
business units within the same processing unit (if processing units are enabled). In such cases, a user
might be able to view balances, deposits, and incentives related to a business unit other than the one they
are assigned to.
• If a participant is assigned to more than one position and those positions are assigned to plans associated
with different calendars, payee payments are not consolidated.
• When you enable payee payment consolidation, you do so for all positions in the system.
• If processing units are enabled, payment consolidation is limited to the confines of a processing unit. For
example, if a participant is assigned to multiple positions and those positions are in different processing
units, payment consolidation only occurs for the positions that are in the same processing unit.
• If payee payment consolidation is enabled, you cannot do a related search from positions to payments, or
vice versa. You can search for related payments from participants.

24.5.2 About Payee Payment Consolidation

From the Participants workspace, you can select a participant and perform a related search to the positions
that the participant is assigned. You can also directly view that participant’s payments by selecting the
participant and performing a related search to payments. In the Payments workspace, when you click the

Incentive Management Admin Design Guide

350 PUBLIC Payments and Balances Overview
Supporting Details tab, the system displays the position information for each deposit. When you expand the
payment details, you can see the results data from multiple positions.

Following are some example calculations, to show you how balancing works with multiple positions and
Consolidate Payee Payments enabled. The following calculations start from the scenario where all periods prior
to January are finalized, and negative payments are not allowed. The following table lists the results as you
would see them in the Payments workspace, Supporting Details tab for the specified position in January. There
are two balances brought over from the prior December period, one of -$500 for the Commission earning
group and another $500 balance from the Bonus earning group.

Calculation Run#1: Compensate and Pay, January run

Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

If negative payments $100 $100 - Position1

were allowed, there
would be a trial pay-
ment in the amount
of -$400 for the
Commission earning
group.

Bonus $500 balance posted $500 $500 - Position2

(unapplied) in Decem-
ber

$500 trial payment

for January

Revenue $1000 trial payment for $1000 $1000 - Position1

January

Calculation Run #2: Compensate and Pay (re-run), January run

Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 351
Earning Group Payment Balance (Prior Period) Earning Deposit & Position

If negative payments $150 $100 - Position1

were allowed, there
$50 - Position2
would be a trial pay-
ment in the amount
of -$350 for the
Commission earning
group.

Bonus $500 balance posted $500 $500 - Position2

(unapplied) in Decem-
ber

$595 trial payment $95 $25 - Position1

for January
$70 - Position2

Revenue $900 trial payment for $900 $900 - Position1

January

 Note

Underlined items indicate changes from the previous table.

The second calculation run is a re-run of Compensate and Pay, without Post. In this second calculation run of
January, the system generates a new trial payment of $595 for the Bonus earning group. The $150 in Earnings
generated for the participant for the Commission earning group is not created as a payment because the prior
period balance is negative and larger than the current period earnings. The Revenue earning group’s earnings
changed to $900 and generated a $900 trial payment.

Calculation Run #3: Post stage, January run

Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

If negative payments $150 $100 - Position1

were allowed, there
$50 - Position2
would be a trial pay-
ment in the amount
of -$350 for the
Commission earning
group.

Bonus $500 balance posted $500 $500 - Position2

(applied) in December

Incentive Management Admin Design Guide

352 PUBLIC Payments and Balances Overview
Earning Group Payment Balance (Prior Period) Earning Deposit & Position

$595 posted pay- $95 $25 - Position1

ment for January
$70 - Position2

Revenue $900 posted payment $900 $900 - Position1

for January

After running the Post stage, the trial status earnings and payments are marked as posted, except for the $150
trial earnings for the Commission earning group. In the Commission earning group, because the prior period
balance is negative and the earnings amount does not balance out the negative portion, no payment can be
generated (the option to allow negative payments is not enabled). This earnings amount stays in trial status.
Later, when the period is finalized, the earnings amount is created as a balance and is available for use in the
next period.

Calculation Run #4: Compensate and Pay (re-run), January run

Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

If negative payments $150 $100 - Position1

were allowed, there
$50 - Position2
would be a trial pay-
ment in the amount
of -$350 for the
Commission earning
group.

Bonus $500 balance posted $500 $500 - Position2

(applied) in December

$595 posted payment $95 $25 - Position1

for January
$70 - Position2

Revenue $900 posted payment $900 $900 - Position1

for January

$90 trial payment for $90 $40 - Position1

January
$50 - Position3

The participant gets assigned to a third position, and Compensate and Pay is re-run for January. The third
position generates new earnings of $50 in the Revenue earning group, and this along with an additional $40
generated in the Revenue earning group by Position1 generates a trial payment of $90 for the Revenue earning
group.

Calculation Run #5: Post stage run, January

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 353
Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

If negative payments $150 $100 - Position1

were allowed, there
$50 - Position2
would be a trial pay-
ment in the amount
of -$350 for the
Commission earning
group.

Bonus $500 balance posted $500 $500 - Position2

(applied) in December

$595 posted pay- $95 $25 - Position1

ment for January
$70 - Position2

Revenue $900 posted payment for $900 $900 - Position1

January

$90 posted payment $90 $40 - Position1

for January
$50 - Position3

After running the Post stage, the trial earnings and payments for the Revenue earning group are marked as
posted, except for the trial earnings for the Commission earning group. Other items are unchanged.

Calculation Run #6: Finalize stage run, January

Earning Group Payment Balance (Prior Period) Earning Deposit & Position

Commission -$500 balance posted -$500 $350 - Position1

(unapplied) in Decem-
-$850 - Position2
ber

$150 balance posted $150 $100 - Position1

in January
$50 - Position2

Bonus $500 balance posted $500 $500 - Position2

(applied) in December

$595 posted payment $95 $25 - Position1

for January
$70 - Position2

Revenue $900 posted payment $900 $900 - Position1

for January

Incentive Management Admin Design Guide

354 PUBLIC Payments and Balances Overview
Earning Group Payment Balance (Prior Period) Earning Deposit & Position

$90 posted payment $90 $40 - Position1

for January
$50 - Position3

After Finalize is run, the trial status earnings of $150 for the Commission earning group is marked as posted
and converted to a balance. If February is run next, there are two unapplied posted balances from the prior
January period (-$500 and $150) in the Commission earning group.

Incentive Management Admin Design Guide

Payments and Balances Overview PUBLIC 355
25 Deletion Policies Overview

When deleting an object that is referred to by another object, the system does one of the following:

• Deletes both the object and the referring object: For example, if you delete a category, the system
automatically deletes the category’s subcategories.
• Disallows deleting the object: For example, the system does not allow you to delete a title if it is assigned
to a position because deleting it would essentially “break” the owning object. Similarly, you cannot delete
objects that are associated with results data (credits, measurements, incentives, deposits, and payments).
• Deletes the object and disassociates it from the referring object: For example, if you delete a position, the
system retains participants that were associated with the position and disassociates the participants from
the position.

Related Information

• Deleting Reference Data [page 356]

• Deleting Administrative Data [page 360]

25.1 Deleting Reference Data

When you delete a reference data object, the system marks all versions of that object as removed from the
Repository. For example, if you delete the participant Michael Robinson on January 15, 2008, his data is
removed for all versions both before and after that date. After an object is deleted, you can find information
about the object only from the Audit Log workspace. The following tables summarizes the actions taken by the
system when you delete reference data (organization data, classification data, plan data, and rules elements)
that is not associated with results data.

Deleting a Participant

Referring Object When you delete a Participant, System Policy is to:

Position Disassociate the position from the participant

Deleting a Title

Referring Object When you delete a Title, System Policy is to:

Position Disallow deleting the title if a position holds it

Incentive Management Admin Design Guide

356 PUBLIC Deletion Policies Overview
Referring Object When you delete a Title, System Policy is to:

Plan Disassociate the plan refers from the title

Variable Assignment Delete the variable assignment

Deleting a Position

Referring Object When you delete a Position, System Policy is to:

Participant Disassociates participants from the position

Title Disassociates title from the position

Manager Disassociates the Manager from the position

Position group Disassociates position groups from the position

Plan Disassociates plans from the position

Subordinates Disassociate the subordinate positions from the position

Relationships to Parent position Delete the relationship to the parent position

Variable Assignments Delete the variable assignments

Results Data Disallow deleting the position if the position has associated
results

Deleting a Position Group

Referring Object When you delete a Position Group, System Policy is to:

Position Disallow deleting the position group if it contains the position

Deleting a Relationship

Referring Object When you delete a Relationship, System Policy is to:

Source position Disassociate the source position from the relationship

Receiver position Disassociate the receiver position from the relationship

Roll Type Disassociate the roll type from the relationship

Deleting a Plan

Incentive Management Admin Design Guide

Deletion Policies Overview PUBLIC 357
Referring Object When you delete a Plan, System Policy is to:

Rules Disassociate the rules from the plan

Calendar Disassociate the calendar from the plan

Positions, Titles Disallow deleting the plan if any positions or titles refer to it

Variable Assignment Delete the variable assignment

Deleting a Rule

Referring Object When you delete a Rule, System Policy is to:

Rule Elements Disassociate the rule elements from the rule

Input References Delete the input references

Output References Delete the output references

Plans Disallow deleting the rule if any plans refer to it

Calendar Disassociate the calendar from the rule

Generic attributes are only referenced by rules. Deleting the rule does not delete the attribute.

Deleting a Formula

Referring Object When you delete a Formula, System Policy is to:

Rules Disallow deleting the formula if any rules refer to it

Rule Element Disallow deleting the formula if any rule elements refer to it

Deleting a Variable

Referring Object When you delete a Variable, System Policy is to:

Default element Disassociate the default element from the variable

Required period type Disassociate the period type from the variable

Assignments Disallow deleting the assigned variable

Rules Disallow deleting the variable if any rules refer to it

Rule Element Disallow deleting the variable if any rule elements refer to it

Deleting a Variable Assignment

Incentive Management Admin Design Guide

358 PUBLIC Deletion Policies Overview
 When you delete a Variable Assignment, System Policy is
Referring Object to:

Owner Disassociate the owner from the variable assignment

Variable Disassociate the variable from the variable assignment

Rule element Disassociate the rule element from the variable assignment

Deleting a Territory

Referring Object When you delete a Territory, System Policy is to:

Variable assignments Disallow deleting the territory if it is assigned to a variable.

Variables Disallow deleting the territory if a variable refers to it.

Rules Disallow deleting the territory if any rules refer to it

Deleting a Rate Table

Referring Object When you delete a Rate Table, System Policy is to:

Variable assignments Disallow deleting the rate table if it is assigned to a variable

Variables Disallow deleting the rate table if a variable refers to it

Rules Disallow deleting the rate table if a rule refers to it

Rule Element Disallow deleting the rate table if any rule elements refer to it

Deleting a Lookup Table

Referring Object When you delete a Lookup Table, System Policy is to:

Rules Disallow deleting the lookup table if any rules refer to it

Rule Element Disallow deleting the lookup table if any rule elements refer
to it

Deleting a Fixed Value

Referring Object When you delete a Fixed Value, System Policy is to:

Rules Disallow deleting the fixed value if any rules refer to it

Variable assignments Disallow deleting the fixed value if it is assigned to a variable

Variables Disallow deleting the fixed value if a variable refers to it

Incentive Management Admin Design Guide

Deletion Policies Overview PUBLIC 359
Referring Object When you delete a Fixed Value, System Policy is to:

Rule Element Disallow deleting the fixed value if any rule elements refer to
it

Deleting a Classifier

Referring Object When you delete a Classifier, System Policy is to:

Category hierarchy Disassociate the category from the classifier

Transactions Disallow deleting the classifier if it has transactions associ-

ated with it

Territory Disallow deleting the classifier if any territory refers to it

Rule Disallow deleting the classifier if any rule refers to it

Deleting a Category

Referring Object When you delete a Category, System Policy is to:

Category hierarchy Disassociate the category from the category hierarchy.

Parent category Disassociate the parent category from the category

Subordinate categories Delete the subordinate categories

Classifiers Disassociate the classifiers from the category

Rule Disallow deleting the category if any rule refers to it

Territory Disallow deleting the category if any territory refers to it

25.2 Deleting Administrative Data

There is no general deletion policy for Administrative Data objects. See the Administrative Tasks
documentation for information about deleting these objects. .

Incentive Management Admin Design Guide

360 PUBLIC Deletion Policies Overview
26 References to Measurements and
Incentives

Each measurement and incentive generated by the Calculation is associated with a period. When using
measurements or incentives in rules, you must consider whether:

• The associated period is at the leaf-level or a higher level period. The leaf-level is the smallest period unit
of your calendar, usually a month or two weeks. When you reference the non-leaf value of a measurement,
you are asking for the sum of leaf values that span the referenced higher-level period.
• The value of measurements or incentives is synthetic or persistent; stored in the database or available
dynamically.
• The rule is references values that it generated (self-referencing).

Measurement or incentives are referred to using Name: period notation. For example, a reference to the
quarter-based version of the GolfPM measurement looks like GolfPM:quarter: UnitType.

Persistent values are the period-based versions of measurements and incentives that the system stores in the
database. For example, the month-based output of a primary measurement rule is a persistent value.

Synthetic values are the higher-level period versions of measurements and incentives that the system
calculates automatically but does not store them in the database. Synthetic values are created to make
processing faster. The system calculates synthetic values during calculation run's and do so regardless of
whether the synthetic values are referenced in any rules. For example, the quarter- and year-based versions of
a primary measurement are synthetic values.

Related Information

• Primary Measurements [page 361]

• Secondary Measurements and Incentives Overview [page 363]
• Period Type Parameters and Rate Tables [page 368]

26.1 Primary Measurements Overview

All primary measurements are aggregates of credits, and therefore primary measurements are leaf-period
values themselves. Credits from multiple leaf periods don’t aggregate into a primary measurement; however,
held credits can be aggregated. For example, credits calculated in January and held until February are
aggregated to the February primary measurement along with February credits.

A primary measurement represents credits for just the leaf period (for example, a month’s worth of credits).
There can be many different primary measurements for a particular period. In most cases, each primary
measurement represents an aggregate of different types of credits; however, depending on the compensation

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 361
rule, you can have multiple primary measurements from the same types of credits. There’s a separate primary
measurement for each leaf period (for example, a month).

Related Articles

• References to Synthetic Versions of Primary Measurements [page 362]

26.1.1 References to Synthetic Versions of Primary

Measurements

While primary measurements are always based on the leaf period’s business activity, a rule can point to
a synthetic version (non-leaf version) of a primary measurement. The value of a primary measurement’s
synthetic version is the sum of the leaf periods within that higher level period, period-to-date. The synthetic
version of a primary measurement includes the current leaf-period value when the offset is 0; however,
depending on the compensation rule, you can also set an offset to 1 quarter and the synthetic value then
includes leaf period values of the prior quarter. For example, in January the value of GolfPM:quarter is only the
January business activity, even if February and March monthly values have already been calculated and you are
rerunning January.

When the system calculates the leaf period values, it automatically calculates the higher level period
values, such as quarter and year versions of primary measurements. These are synthetic values and the
system does not store these higher level period values in the database. For example, when the system
calculates the monthly value for April (GolfPM:month), it automatically calculates the higher level period
values (GolfPM:quarter and GolfPM:year). GolfPM:quarter and GolfPM:year are available for use in rules and
calculations, but they are not stored in the database. They are available during a calculation run.

In April, the value of GolfPM:quarter is $550. This value represents the quarter-to-date revenue for the second
quarter. To summarize, the synthetic version of a primary measurement represents the period-to-date value.
This includes the current leaf period value if the offset is not used (0).

 Note

For most references, the current period’s value is included. The exception is for self-references.

Related Information

Primary Measurements Overview [page 361]

Incentive Management Admin Design Guide

362 PUBLIC References to Measurements and Incentives
26.2 Secondary Measurements and Incentives Overview

Secondary measurements and incentives are also calculated monthly, and they can represent business activity
either for a distinct leaf period or over multiple leaf periods. A secondary measurement can aggregate the
data from other primary measurements. An incentive can aggregate the data from measurements or other
incentives. The following figure illustrates an example of a secondary measurement that represents a month’s
worth of business activity.

In the example illustrated previously, the Total Revenue secondary measurement aggregates the monthly
GolfPM and AircraftPM values. The following figure illustrates an example of a secondary measurement that
represents a quarter-to-date amount of business activity.

This is a secondary measurement that is based on three months’ worth of data for two product lines (quarter
to date). This secondary measurement calculates monthly but represents the quarter to date total. Every
month, this secondary measurement calculates the quarter-to-date value so far for the current quarter.

Related Articles

• Persistent and Synthetic Versions of Measurements [page 363]

• Persistent and Synthetic Versions of Incentives [page 363]
• References to Measurements and Incentives [page 364]
• Issues with References to Secondary Measurements and Incentives [page 365]

26.2.1 Persistent and Synthetic Versions of Measurements

For primary and secondary measurements, the system creates the persistent version for the leaf level period
(for example, month). The system also calculates the synthetic, higher level period values for the measurement
(for example, quarter and year versions).

Related Information

Secondary Measurements and Incentives Overview [page 363]

26.2.2 Persistent and Synthetic Versions of Incentives

The system generates persistent and synthetic versions of incentives similar to those for measurements.
However, incentives are not necessarily based on the leaf period. When you create an incentive rule, you specify
the period type for the output of the rule. Commissions generates synthetic versions of incentives only for
those periods that are of a higher level than the period type of the incentive itself.

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 363
For example, you can have a quarterly incentive rule that pays out a bonus once a quarter. For this rule, the
system would calculate and store a persistent value for the quarter period, and would calculate a synthetic
value for the year period. In this case, the system would not create a month-based version for a quarterly
incentive rule.

As shown, the system stores the quarterly GolfBonus value with the quarter period. Each month, the system
calculates the GolfBonus value and overwrites the previous month's calculation within the quarter, until the last
month in the quarter when the bonus is released for deposit. An incentive based on a higher-level period is
available for deposit during the last leaf period within the specified higher level period type. The last leaf period
of a higher level period is determined by the period type of the higher level period. For example, a quarterly
incentive is available for deposit during the last month in each quarter.

 Example

Example: In January, the GolfBonus value is $50. In February, the system overwrites the January
calculation and stores the February calculation, which is now $115. In March, the system overwrites the
February calculation and stores the March calculation of $155. Because March is the end of the quarter, the
quarterly GolfBonus is released for deposit in March.

Each month the system calculates the quarterly bonus, but each month in the quarter it overwrites the
previous month’s calculation. The system releases the bonus for deposit in the last month of the quarter.

Related Information

Secondary Measurements and Incentives Overview [page 363]

26.2.3 References to Measurements and Incentives

A reference is a method of including a measurement or incentive value in another rule or in a formula. The
reference acts as a placeholder for the measurement or incentive from the specified period type relative to the
current processing period. The following figure illustrates an example of a quarterly incentive rule that refers to
the quarter-based version of a primary measurement.

For example, to use the quarter-based version of the GolfPM measurement in an incentive rule called
GolfBonus, you include a reference to the GolfPM measurement in the GolfBonus rule, and you specify
“quarter” as the period type. When the GolfBonus rule runs in March, it gets the quarter-based version of
the GolfPM measurement that is calculated in March, which is essentially a quarter-to-date value. The March
quarter-based version of the GolfPM measurement includes the monthly values from January, February, and
March. When the GolfBonus rule runs in May, it gets the quarter-date amount of the GolfPM measurement. The
May quarterly version of the GolfPM measurement includes the monthly values from April and May.

For references to measurements, you specify the period-based version by specifying the measurement.

For references to incentives, you specify the period-based version by specifying the incentive period.

Incentive Management Admin Design Guide

364 PUBLIC References to Measurements and Incentives
Related Information

Secondary Measurements and Incentives Overview [page 363]

26.2.4 Issues with References to Secondary Measurements

and Incentives

You can include a reference to the leaf or higher-level period versions of primary measurements. Because
primary measurements always represent business activity from one leaf period, both the leaf or higher-level
period versions make sense to use. However, unlike primary measurements, secondary measurements and
incentives frequently represent data that crosses leaf period boundaries.

For example, you can include a reference to the quarterly value of the GolfPM measurement to get the sum of
the monthly values in a particular quarter. As another example, a secondary measurement can, each month,
calculate the Golf Revenue quarter-to-date, as shown in the following figure. This secondary measurement
calculates a quarter-do-date amount each month. The leaf-level versions already represent an aggregation of
data. If you refer to a non-leaf level version of this secondary measurement, you are referring to a redundant
aggregation of data (Jan.) + (Jan. + Feb.) + (Jan. + Feb. + Mar).

For secondary measurements and incentives, you can refer to either the leaf or non-leaf versions of them.
However, referring to the non-leaf version only makes sense when the referenced secondary measurement or
incentive represents data from a single leaf period.

If you reference a secondary measurement or incentive in a way that uses a redundant aggregation of data,
your payees you are likely to be overcompensate. For example, as shown in the following figure, suppose you
want to specify a measurement reference in an incentive rule and that you have two measurements to choose
from:

• A primary measurement that calculates a month-to-date revenue.

• A secondary measurement that calculates quarter-to-date revenue

In this example, if you create a bonus rule to calculate 10% of the measurement value, the result varies
depending on which measurement value you choose.

Calculation Based on Different Measurements

Measurement Calculation

GolfPM:quarter 10% X GolfPM:quarter GolfPM:quarter = (GolfPM:month (April) + GolfPM:month (May) +

GolfPM:month (June))

= 10% X (55 + 45 + 70) = 10% X 170 = $17 bonus

GolfRevQTD:month 10% X GolfRevQTD:month (June) = 55 + 45 + 70 = 10% X 170 = $17 bonus

GolfRevQTD:quarter 10% X GolfRevQTD:quarter = 55 + (55 + 45) + (55 + 45 + 70) = 55 + 100 + 170 = 10% X
325 = $32.50 bonus

If you use GolfPM:quarter or GolfRevQTD:month for the measurement, the bonus is calculated as $17. If
you use the GolfRevQTD:quarter measurement, the bonus is calculated as $32.50.When you use the quarter-

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 365
to-date measurement, the result is an overpayment because the measurement results in the redundant
aggregation of credits.

Related Information

Secondary Measurements and Incentives Overview [page 363]

26.3 Self-Referencing Rules

You can create a rule that is self-referencing, meaning that the rule creates a measurement or incentive and
refers back to the value of that measurement or incentive. You might need to create a self-referencing rule if
you need to verify if the value exists already. For example, you want to pay an Over Quota Bonus that fulfills the
following requirements:

• In the first period that performance is over quota, pay a $5000 bonus.
• If the bonus has already been paid during the current fiscal year, do not pay the bonus again.
• If the bonus has already been paid but performance goes below quota in a later period (such as from a
debooking), recover the bonus.

The Over Quota Bonus pays as illustrated in the following figure.

To handle the Over Quota Bonus, create two incentive rules: one to handle the creation of the bonus, and the
other to handle the recovery of the bonus. The following figure shows the definitions of each of these rules.

Incentive Rules for Bonus Generation and Recovery

Rule #1 Rule #2

rule name OverQuotaBonusGeneration OverQuotaBonusRecovery

output name OverQuotaBonus OverQuotaBonus

period type month month

condition if revenue.year > quota.year if (revenue.year < quota.year)

AND

(OverQuotaBonus.year > 0)

bonus amount $5000 - (OverQuotaBonus.year) 0 - (OverQuotaBonus.year)

In Rule#1, the self-reference is in a monthly incentive rule, and the reference is to the year-based version of the
rule’s output. In Rule#2, the output is the same name as the output from Rule #1. The two rules have outputs of
the same name because they handle all conditions for generating and recovering the same bonus.

To continue the self-reference example, here are the rule output values for January through July:

Bonus Output Values

Incentive Management Admin Design Guide

366 PUBLIC References to Measurements and Incentives
 Jan Feb Mar Apr May Jun Jul

over quota? not over not over not over not over over quota still over not over
quota quota quota quota quota quota

OverQuotaBonus.month 0 0 0 0 $5000 0 -$5000

OverQuotaBonus.year 0 0 0 0 $5000 $5000 0

In May, the payee’s revenue first exceeds the quota.

Revenue.year > quota.year, so OverQuotaBonus.month = $5000 - OverQuotaBonus.year = $5000 - 0 = $5000

 Note

Because this is a self-reference, the year-based version in May does not include May’s monthly value. The
value that’s used is the same amount as the April value.

In June, the payee’s revenue is still over quota:

Revenue.year > quota.year, so OverQuotaBonus.month = $5000 - OverQuotaBonus.year = $5000 - $5000 =

$0

In July, a debooking occurs that results in the payee’s revenue now being under quota.

(Revenue.year > quota.year) AND (OverQuotaBonus.year > 0), so OverQuotaBonus.month = $0 -

OverQuotaBonus.year = $0 - $5000 = -$5000

 Note

The year-based version of this self-reference does not include July’s value. The value that’s used is the
same as the June value.

The OverQuotaBonusRecover rule runs instead of the OverQuotaBonusGeneration rule.

 Note

A self-referencing rule cannot refer to the same period-based version as the rule itself creates. For
example, if you create a quarterly bonus rule, then if you refer to the output of the rule, you can only
refer to the year-based version of the bonus.

26.4 Synthetic Values and Sum Functions

To obtain values to use to determine performance progress so far during a period, use the functions Sum
Measurements Period to Date and Sum Incentives Period to Date. These functions show accumulation period
to date. The values returned by these functions shows accumulation toward a goal that you can compare,
usually through a condition, to something else to determine attainment. The details indicate which value and
how much of it to sum. Use a synthetic value instead of a sum period to date function whenever possible.
It is faster to process a reference to a synthetic object if you want to include a higher-level period version of
a measurement or incentive. For example, to use the year-to-date value of a revenue measurement, you can

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 367
either reference the synthetic value of the year-to-date measurement, or use the Sum Measurements Period to
Date function. The latter option requires calculation and a call to the database.

26.5 Period Type Parameters and Rate Tables Overview

When you create an incentive rule with a rate table, you must specify additional period versions, for example,
in a step commission rule. When you create an incentive rule with a rate table, you must specify the following
period type parameters:

• Measurement period

The period type that specifies the performance measurement for which the participant should be paid. For
example, if the incentive rule’s measurement period = month, the commission rates (in the rate table) apply to
the incoming revenue measurement for each month.

• Attainment period

The period type for which attainment is measured; the attainment level determines the applicable rate (from
the rate table). For example, an incentive rule could determine the attainment level by the quarter-to-date
performance (attainment period=quarter), while paying for just the new revenue each month (measurement
period=month).

Period Type Parameters for Use with Rate Tables

Period Type Parameter Is the answer to the following question:

Measurement Period For what incremental revenue does the participant get paid this period?

Attainment Period What revenue period to date is compared to the quota to calculate the attain-
ment?

What revenue period to date represents the attainment?

26.5.1 Period Type Parameter Examples

The examples in this section illustrate the effects of specifying different combinations of measurement period
and attainment period for a sample monthly incentive rule that uses a rate table to calculate the commission.

Measurements and Rate Tables: Scenario 1, Good Practice

In this example, the following period type parameters are specified:

Period Type Parameters: Scenario 1, Good Practice

Period Type Parameter Value

measurement period month

Incentive Management Admin Design Guide

368 PUBLIC References to Measurements and Incentives
Period Type Parameter Value

attainment period quarter

This scenario pays commission on the monthly revenue, and the pay rate is determined by the quarter-to-date
performance. This scenario pays appropriately.

The following table lists the calculations that occur for this incentive rule for the four sample months, January
through April. Commissions are appropriate to the generated revenue (neither overpaid or underpaid).

Scenario 1 Commission Calculations

Measurement Reve-
Attainment nue Commission

January =2500/6000 = 41.67% 2500 1st tier =2500 X 5% = $125 commission

February =(2500 + 3000)/6000 3000 1st tier = 500 X 5% = $25

= 5500/6000 2nd tier = 2500 X 10% = $250

= 91.67% total commission = $275

March =(5500 + 1800)/6000 1800 rest of 2nd tier= $500 X 10% = $50

= 7300/6000 3rd tier = $1300 X 15% = $195

= 122% total commission = $245

April = 3500/7000 = 50% 3500 1st tier = 3500 X 5% = $175 commission

Total Com- = $820

missions Jan-
uary through
April

Measurements and Rate Tables: Scenario 2, Bad Practice

In this example, the following period type parameters are specified:

Period Type Parameters: Scenario 2, Bad Practice

Period Type Parameter Value

measurement period quarter

attainment period quarter

This scenario pays commission on quarter-to-date revenue each month, and the pay rate is determined by the
quarter-to-date performance. This scenario overpays, by paying on the January revenue three times, and the
February revenue two times.

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 369
The following table lists the calculations that occur for this incentive rule for the four sample months, January
through April. Commissions are not appropriate to the generated revenue, as commissions are paid multiple
times for January and February.

Scenario 2 Commission Calculations

Measurement Rev-
Attainment enue Commission

January =2500/6000 = 41.67% 2500 1st tier =2500 X 5% = $125 commission

February =(2500 + 3000)/6000 5500 1st tier = 3000 X 5% = $150

= 5500/6000 2nd tier = 2500 X 10% = $250

= 91.67% total commission = $400

March =(5500 + 1800)/6000 7300 1st tier = 3000 X 5% = $150

= 7300/6000 2nd tier = $3000 X 10% = $300

= 122% 3rd tier= $1300 X 15% = $195

total commission = $645

April = 3500/7000 = 50% 3500 1st tier = 3500 X 5% = $175 commission

Total Com- = $1345

missions
January
through April

Measurements and Rate Tables: General Guideline Summary

To summarize, when you create an incentive rule that uses a rate table, be careful about the period versions
that you specify. A secondary measurement rule can calculate year-to-date revenue on a monthly basis
(attainment period=month). To use this kind of measurement with a rate table in an incentive rule, you would
use an annual quota (quota period=year).

26.6 Using Period-Based Versions of Measurements and

Incentives Summary Guidelines

• When you reference the non-leaf value of a measurement, you are asking for the sum of leaf values that
span the referenced higher-level period.
• For all non-self-referencing measurements and incentives, the reference includes the current period if the
offset is not used.

Incentive Management Admin Design Guide

370 PUBLIC References to Measurements and Incentives
• Self-referencing measurements and incentives can never include the current period.
• If the secondary measurement or incentive calculates data that crosses leaf-period boundaries, 99% of the
time you should use the leaf-period version.
• For references to measurements for use in a rate table, attainment period is an additional criterion.
• Use a synthetic value whenever possible instead of a sum to date function.

Incentive Management Admin Design Guide

References to Measurements and Incentives PUBLIC 371
27 Modeling

The Modeling feature in SAP SuccessFactors Incentive Management enables you to create model scenarios to
predict the impact of proposed changes to compensation plans.

Modeling empowers compensation administrators to:

• modify compensation plan components and simulate the effects of proposed changes.
• perform macro level and payee level modeling for overall cost impact analysis and control compensation
spend.
• make informed decisions for optimal business outcomes.

After designing a model scenario, you can perform a Model Run. A Model Run, similar to a calculation run,
generates model period data from historical primary measurements based on the provided specifications.

The modeling process extracts period-over-period trends and generates model data from historical records.

Related Information

Modeling Workspace [page 372]

Modeling Workspace [page 372]

27.1 Modeling Workspace

The Modeling workspace clearly segregates the modeling data from production data enabling you to
seamlessly create, test, and implement incentive plans. Changes made to modeled objects do not affect
production objects. New objects created for modelling purposes are not visible in production environments.

 Note

You must have the required permissions settings configured in Incentive Management Admin > Manage
Setup > Security > Roles > Permissions > Models to access and use the Modeling application. If you
have questions about your login credentials and permission settings, contact your administrator.

In the Apps drop-down, choose Modeling to access the Modeling application.

Incentive Management Admin Design Guide

372 PUBLIC Modeling
The Models page displays a list of all the existing models.

The following actions can be performed in the Models page:

Action Description

Create Model Create a new model.

View Report Displays the report (results) of the model run.

Delete Delete a model.

Search Performs a search based on the search term

Related Information

Modeling [page 372]

Creating and Running Models [page 374]
Viewing Notifications [page 381]

Incentive Management Admin Design Guide

Modeling PUBLIC 373
27.2 Creating and Running Models

The Modeling feature provides capabilities to empower administrators with the foresight to optimize
compensation plans effectively.

Prerequisite

To access the Modeling application, administrators must configure appropriate permission settings in
Incentive Management Admin > Manage Setup > Security > Roles > Permissions. See Permission Set for
more details.

Procedure

1. In the Apps drop-down, choose Modeling.

2. Choose Create New Model in the top-right. The Create New Model page is displayed.
3. Under Model Name, provide the following details:
• Model Name: A unique name given for the model.
• Model Description: A brief description of the model.

4. Choose Next.
5. Under Model Details, provide the following details:
• Calendar: Calendar for the source/planning periods.
• Source Date for Model: The period range from which actuals are obtained and model data is created.
A Source period has the following main functions:
• It enables determining which plans can be added as part of the model.
• Historical organization and classification reference data from the Source period is used in the
model.
• Historical transaction or measurement data from the Source period can be used as an input to the
model (simulated data or projected data can also be used as an input to the model).
• Model calculation results are created in the Source period, but under the model context.
• Processing Unit: Allows you to filter model data through a processing unit. This option is only available
if the Use Processing Units option is selected in Calculation Preferences.

Incentive Management Admin Design Guide

374 PUBLIC Modeling
6. Choose Next.
7. Under Plan Options, provide the following details.
• Select the plan to be added to the model. All compensation elements tied to the selected plan will be
incorporated based on the chosen source periods. You can select multiple plans simultaneously and
edit the available plan components across the selected plans in the same step.
• Rules
• Rate tables: See Adjusting Rate Tables [page 377] for details.
• Fixed Values: See Adjusting Fixed Values [page 378] for details.
• Formulas
• Territories
• Lookup Tables
• Variables

8. Choose Next.
9. Under Model Summary, you can view the summary of the model and make changes if necessary, before
running the model.

Incentive Management Admin Design Guide

Modeling PUBLIC 375
10. Choose Run Model to run the model. The Run Model dialog is displayed.
• Specify the period to run the model for if you want to run the model for a specific period (not as
defined in the plan).
• You can run All plans in the selected period or you can run Only modeled plans to quickly analyze
specific scenarios without unnecessary processing.
• If you do not have any results data for the model periods, or you have results data that can
be overwritten, choose Proceed. If you do not want to overwrite data in the model periods,
choose Cancel to exit.

11. After you choose Proceed, you are redirected to the Modeling page and a confirmation message is
displayed stating that the calculation has started. Once the calculation is completed, you will be notified.
After the model run is completed, choose the View Report option in the Modeling page to view the results
and logs.

Incentive Management Admin Design Guide

376 PUBLIC Modeling
 You can use various dimensions and unit types available in the report to analyze the impact of the
proposed compensation plan. See Model Report [page 378] for more details.

Related Information

Modeling [page 372]

Modeling Workspace [page 372]

27.2.1 Adjusting Rate Tables

You can make dynamic adjustments to rate tables within a model to reflect desired changes in compensation.

You can add or delete tiers within rate tables, enabling more dynamic adjustments to business requirements
without the need to create entirely new rate tables. When adding a new tier, you can define the bounds and
specify the rate or formula

You can add new tiers or adjust existing tiers in rate tables by modifying the following and then run the
modelling calculations to see the results of these modifications:

• Operator
• Attainment
• Rate

Incentive Management Admin Design Guide

Modeling PUBLIC 377
  Note

Rate tables have editable operators, rates, and attainments. The formula is read-only and cannot be
changed, but the row containing it can be deleted.

Related Information

Creating and Running Models [page 374]

About Rate Tables [page 229]

27.2.2 Adjusting Fixed Values

You can make adjustments to the Fixed Values within a model to reflect desired changes in compensation and
then run the modelling calculations to see the results of these modifications.

Related Information

Creating and Running Models [page 374]

Fixed Values Overview [page 215]

27.3 Model Report

After the model run is completed, choose the View Report option in the Modeling page to view the results and
the logs.

Incentive Management Admin Design Guide

378 PUBLIC Modeling
The View Report tab presents detailed insights including total model cost, actual plan expenses, deviation
analysis, and more. The chart view feature enables you to visualize reports. Additionally, you can filter data at
the payee level to view individual payee-level details.

When the Measurement, Incentive, or Deposit filter is selected, the report shows the model total cost, the
actual plan cost, and deviation for the selected measurement, incentive, or deposit. When the Unit Type filter is
selected, the report shows the model total cost, the actual plan cost, and deviation for the selected unit type.

The chart view shows the model total cost, the actual plan cost and the deviation for the period. In chart view,
users can view payee level details including actual and model value per user-per rule by selecting a user in the
filter.

Incentive Management Admin Design Guide

Modeling PUBLIC 379
Related Information

Creating and Running Models [page 374]

Model Run Logs [page 380]

27.4 Model Run Logs

When the model run is complete, choose Completed or the View Report option to view the history logs.

If the log shows any failures, you can rerun the model or contact the administrator if the problem persists.

Incentive Management Admin Design Guide

380 PUBLIC Modeling
Related Information

Creating and Running Models [page 374]

27.5 Viewing Notifications

The Notifications feature in Modeling displays real-time notifications related to the status of the Model Runs.

Choose Notifications in the top-right of the page to view the notifications.

The most recent notifications are displayed on top. Choose View All to view all the notifications.

You can search for a particular notification.

You can also use the Unread Only toggle button to view only unread notifications.

Incentive Management Admin Design Guide

Modeling PUBLIC 381
Related Information

Modeling [page 372]

Creating and Running Models [page 374]

27.6 Using Proxies

From the profile option in the top-right, choose Proxies to access the proxy functionality. See Managing Your
Proxy Relationships for more details.

In My Proxies tab, you can view a list of users who can proxy as you.

In Proxy As, you can select the user you want to proxy as. If configured by the administrator, you may need to
reauthenticate when you attempt to log in as a proxy user.

To exit a proxy, select Profile > Exit Proxy.

Incentive Management Admin Design Guide

382 PUBLIC Modeling
Related Information

Modeling Workspace [page 372]

Incentive Management Admin Design Guide

Modeling PUBLIC 383
28 Integration

This section provides information about the various other integrations that are related to SAP SuccessFactors
Incentive Management.

This integration help content is meant for SAP customers, partners, consultants, and employees. It provides
information and support for the following roles that are involved in the integration project:

• Integration project managers and team members

• SAP customer system administrators
• SAP SuccessFactors Incentive Management consultants

Related Information

• Integration with SAP S/4HANA Cloud and S/4HANA Private Cloud [page 384]
• Integration with SAP IdP [page 408]
• Integration with SAP Business Technology Platform (BTP) [page 446]
• Integration with SAP Data Custodian [page 506]
• Data Integration and Management Solutions [page 522]
• API Authentication [page 508]
• Integration with SalesForce for Incentive Management Portal

28.1 Integration with SAP S/4HANA Cloud and S/4HANA

Private Cloud

This section describes the integration setup for an SAP S/4HANA instance with SAP SuccessFactors Incentive
Management Cloud using SAP Integration Suite.

Integration Scope

The following images depict the integrated functional scenarios at a high level.

Incentive Management Admin Design Guide

384 PUBLIC Integration
Integration Flow Methodology

You need to choose the integration flow that best fits your business requirements.

• Replicate Sales Order Items from SAP S/4HANA: Choose this method if you want to calculate payments in
SAP SuccessFactors Incentive Management based on SAP S/4HANA Sales Orders.
• Replicate Billing Document Items from SAP S/4HANA: Choose this method if you want to calculate
payments in SAP SuccessFactors Incentive Management based on SAP S/4HANA Billing Documents.
• Replicate Product Master Data from S/4HANA: Additionally, you can replicate product master data from
S/4HANA if you want to include some product details in the payment calculations.
• Replicate Sales Contract Items from SAP S/4HANA: Choose this method if you want to calculate
payments in SAP SuccessFactors Incentive Managementt based on SAP S/4HANA Sales Contracts.
• Replicate Sales Quotation Items from SAP S/4HANA: Choose this method if you want to calculate
payments in SAP SuccessFactors Incentive Management based on SAP S/4HANA Sales Quotations.
• Replicate Customer Master Data from S/4HANA: Choose this method if you want to replicate customer
master data from S/4HANA if you want to include customer details in the payment calculations.
• Replicate Product Hierarchy Nodes from SAP S/4HANA Private Cloud: Choose this method if you want
to replicate product hierarchy nodes from S/4HANA Private Cloud (hierarchy type MARA) if you want to
include product hierarchy in the payment calculations.
• Replicate Service Contract Items from SAP S/4HANA: Choose this method if you want to calculate
payments in SAP SuccessFactors Incentive Management based on SAP S/4HANA Service Contracts.

For more information, see Integration Flow Prerequisites [page 387].

Incentive Management Admin Design Guide

Integration PUBLIC 385
Architecture of the Integration Flow

The timer-driven integration is configurable and extendable. OData V2 is used in an SAP S/4HANA instance to
get the data and Express Data Loader (XDL) is used in an SAP SuccessFactors Incentive Management instance
to upload the transactions.

Limitations of the Integration Flow

Integration flow limitations are as below:

• Deleted Sales Entities and Items cannot be synchronized, so you must not delete Sales Entities and Items
from the SAP S/4HANA system. You must use the Sales Orders Block status or the Reason for Rejection
at the item-level so the flow can replicate it in SAP SuccessFactors Incentive Management.
• The maximum number of Sales Entity Items or Billing Document Items that the flow can process in one
run is up to 20000 if an extension is not defined. When an extension is defined, up to 10000 records
can be processed. If your system contains more than 20000 records, you can schedule the flow to run in
short periods (for example, every 10 minutes). Each run continues the processing from the item where the
previous run was stopped, and in each run, the flow can process the next batch of 20000 records. Based
on this method, and our S/4 Hana Cloud performance tests, a daily maximum of about 2.7 million records
can be processed. On S/4 HANA private cloud instance, the flow can be scheduled to run every 5 minutes
and a daily maximum of 5.8 million records can be processed.

Incentive Management Admin Design Guide

386 PUBLIC Integration
• Sales Entity that does not have a Currency defined cannot be imported into SAP SuccessFactors Incentive
Management.
• In S/4HANA, products can be related to one or many Sales Organizations. Each Product-Sales
Organization relation is replicated as a separate Classifier record in Incentive Management. Products
without Sales Organization relations are not replicated in Incentive Management. The number of products
processed in one S/4HANA batch may not match the number of Classifiers replicated to Incentive
Management in the same batch. The counts of processed S/4HANA products and replicated Classifiers in
Incentive Management are logged and available in the SAP Integration Suite Message Monitor.
• Product Hierarchy Nodes replication is supported only for Product Hierarchy type MARA for S/4HANA
Private Cloud.

Considerations for Sales Entity Changes

• Scenario 1:
• Adding New Items in an Existing Sales Entity: The newly added items will be replicated to Incentive
Management. However, to reflect these new items in already calculated payments, you need to re-run
the pipeline.
• Scenario 2:
• Header Level Changes: All items within the Sales Entity will be updated through the XDL process to
reflect the changes.

Related Information

Integration with SAP S/4HANA Cloud and S/4HANA Private Cloud - Glossary [page 407]

28.1.1 Integration Flow Prerequisites

The following prerequisites must be configured for the chosen integration flow:

• Products will be replicated into Incentive Management at the Classifier level in the Product Tree Category.
The first S4 Hierarchy level will be referenced as the IM category of the Product. It is the responsibility of
the customer to set up the Incentive Management Hierarchy as required with at least the first level being
the same as S4. The structure above this level should also be defined by the Customer either reflecting
the S4 structure or as is often the case, flattening or expanding the structure as needed for Incentive
Management. If the first level S4 Hierarchy category is not set up in Incentive Management, then the
product will not be added and thus giving Incentive Management control over what products are replicated.
When a Product is loaded with an S4 Hierarchy level that does not exist in Incentive Management the
line will be recorded as an error in the load. If the product is needed then the category can be added to
Incentive management and the load re run. If there are significant groups of Products that are not needed
then the iflow can parameterized to explicitly filter these groups from the extract and thus remove the
products from the error report. Due care should be taken, if in the future, such products are needed, to
maintain the parameterized flow to include these previously excluded product groups.

Incentive Management Admin Design Guide

Integration PUBLIC 387
• The integration flow adds the respective S/4HANA Sales Entity Partner Sales Employee as an assignee
to the Incentive Management transaction. All relevant SAP S/4HANA employees need to be present in
Incentive Management Admin as Participants. The Incentive Management Participant ID is equivalent the
SAP S/4HANA Employee ID.
• The integration flow maps the respective S/4HANA Sales Entity type to the Incentive Management
transaction Event Type. All relevant SAP S/4HANA order types must be added as event types in the
Incentive Management configuration. See Event Types documentation for more information. By default,
the Replicate Sales Order Items from SAP S/4HANA flow synchronizes only Sales Orders with the
event type ‘OR’. For the Replicate Billing Document Items flow, all types of Billing Documents will be
synchronized.
• All relevant SAP S/4HANA currencies that are used in S/4HANA Sales Entities must be added to the
Incentive Management configuration: See Unit Types documentation for more information.

Replicating S/4HANA Sales Entity Items from SAP S/4HANA

This integration flow replicates S/4HANA Sales Entity Items from SAP S/4HANA to SAP SuccessFactors
Incentive Management Transactions. The timer-initiated integration flow is enabled to run in different modes
using external parameters and local variables.

The SAP Integration Suite variable is used to store the information about the last synced item. The variable
reflects the exact date and time when the last synced order was last updated in SAP S/4HANA. The variable
name is defined in Flow Configuration > More > Last Processed Time Global Variable field.

Once the flow is run and completed successfully for the first time, the variable is saved to a specified location
(Monitor > Integrations > Variables).

After the variable is saved, subsequent flows will run in delta mode, starting the sync from the last synced
order, and then saving the new timestamp each time a new flow is successfully finished.

To run in full mode (that is, sync all order item lines from the beginning), there are two options:

1. Define a new name in the Flow Configuration > More > Last Processed Time Global Variable field.
2. Delete the existing variable from Monitor > Integrations > Variables.

The difference between the two options is that if you use the first option, you can still rerun from the last
synced order prior to full mode. Based on external parameters, the integration flow can run in these models:

• Transactions with assignees: Replicate S/4HANA Sales Entity Items with Partner Function Sales Employee
from SAP S/4HANA to SAP SuccessFactors Incentive Management Transactions with associated
participants (value is selected in Flow Configuration > More > Transactions with Assignee)
• Transactions without assignees: Replicate S/4HANA Sales Entity Items from SAP S/4HANA to SAP
SuccessFactors Incentive Management Transactions without associated participants (value is not selected
in Flow Configuration > More > Transactions with Assignee)

Integration Flow Steps

The integration flow is defined to perform the following steps:

Incentive Management Admin Design Guide

388 PUBLIC Integration
1. Run the flow by scheduled timer.
2. Call the SAP S/4HANA OData API to get the data of all newly added or changed Sales Orders/Billing
Documents since last run.
3. Filter out S/4HANA Sales Entity without currency defined since those cannot be imported into SAP
SuccessFactors Incentive Management.
4. Map result payload data to Transactions with assignees/Transactions without assignees based on the
business logic defined in the Message Mapping.
5. Create CSV files based on Express Data Loader (XDL) templates
6. Send results to the SAP SuccessFactors Incentive Management system SFTP in CSV format.
7. Save the change date of last S/4HANA Sales Entity in global variables, after successful completion of
related processes in the SAP Integration Suite.

28.1.2 System Preparation for Data Replication

The following systems need to be prepared for data replication:

• Preparing SAP S/4HANA for Data Replication [page 390]

• Preparing SAP SuccessFactors Incentive Management for Data Replication [page 391]
• Preparing SAP Integration Suite for S/4HANA Sales Entity Records Replication [page 391]

Incentive Management Admin Design Guide

Integration PUBLIC 389
28.1.2.1 Preparing SAP S/4HANA for Data Replication

The integration flows call OData services in SAP S/4HANA to read respective S/4HANA Sales Entity records.
This action requires:

• A communication system
• A communication user
• A communication arrangement

For more information, see Communication Management in SAP S/4HANA.

Additionally, for S/4HANA Private Cloud instance:

• OData service groups need to be published. For more information, see Service Group Publishing.
• Cloud Connector is used as a link between SAP BTP applications and the Private Cloud system. For more
information, see Cloud Connector.

Integration Flows

• The Replicate Sales Order Items from SAP S/4HANA integration flow uses the Sales Order OData. See the
OData Sales Order for information on the communication scenario that needs to be added.
• The Replicate Billing Document Items from SAP S/4HANA integration flow uses the Billing Document
OData. See the OData Billing Document for information on the communication scenario that needs to
be added.
• The Replicate Product Master Data from S/4HANA integration flow uses the Product Master OData. See
the OData Product Master documentation for information on the communication scenario that needs to
be added.
• The Replicate Sales Contracts Items from SAP S/4HANA integration flow uses the Sales Contracts OData.
See the OData Sales Contracts for information on the communication scenario that needs to be added.
• The Replicate Sales Quotation Items from SAP S/4HANA integration flow uses the Sales Quotations
OData. See the OData Sales Quotation documentation for information on the communication scenario
that needs to be added.
• The Replicate Customer Master Data from S/4HANA integration flow uses the Business Partner Master
OData. See the OData Business Partner Master documentation for information on the communication
scenario that needs to be added.
• The Replicate Product Hierarchy Nodes Data from S/4HANA Private Cloud integration flow uses the RFC
( BAPI_MATERIAL_GET_PRODUCTHIER ). In order to use RFC from Integration Suite flow, add the RFC
destination to BTP instance as described in the SAP BTP Connectivity (RFC Destinations) documentation.
• The Replicate Service Contract Items from SAP S/4HANA integration flow uses the Service Contract
OData. See the OData Service Contract for information on the communication scenario that needs to be
added.

Incentive Management Admin Design Guide

390 PUBLIC Integration
28.1.2.2 Preparing SAP SuccessFactors Incentive
Management for Data Replication

This section describes the steps involved in preparing SAP SuccessFactors Incentive Management for data
replication.

Prerequisites

• SAP SuccessFactors Incentive Management tenant must have Express Data Loader setup. See Express
Data Loader for more information.
• The user must have administrator user rights to access Express Data Loader.

Procedure

1. Log in to SAP SuccessFactors Incentive Management and select Express Data Loader from the application
menu in the top-right.
2. Choose Configuration > File Type Setup.
3. Find the file type TXSTA > Inbound and choose Edit.
4. Select the Delimiter value as Pipe.
5. Select the Import Type value as Validate And Transfer.
6. Choose Save.
7. Repeat steps 3 through 6 for file types TXST and TXTA. For replication of Product Master Data, repeat
steps 3 through 6 for file type CLPR.

28.1.2.3 Preparing SAP Integration Suite for S/4HANA Sales

Entity Records Replication

This section describes the steps involved in preparing SAP Integration Suite for S/4HANA Sales Entity Records
replication.

Prerequisites

To deploy the SAP Integration Suite flows, you must have the SAP Integration Suite tenant initialized and
have the user with required permission roles assigned. See SAP Integration Suite - Initial Setup for more
information.

Incentive Management Admin Design Guide

Integration PUBLIC 391
Procedure

 Note

Each Integration Suite tenant has its own SSH key, and this key cannot be shared across tenants.

To configure SAP Integration Suite for Sales Order/Billing Document data replication, perform the following:

1. In SAP Integration Suite, go to Monitor > Integrations > Manage Security > Keystore .
2. Choose Create > SSH Key to create a key pair for SFTP connectivity.
3. Deploy the SSH Key with the following attributes:

Field Name Value

Alias Enter any name.

Key Type Select RSA

Key Size Select 2048

Signature Algorithm Select SHA-512/RSA

Common Name (CN) Enter any name.

Country/Region Enter your country/region

Valid From Select Validity Start Date

Valid Until Select Validity End Date

4. Download the Public Open SSH Key of the deployed Key Pair.
5. In SAP SuccessFactors Incentive Management > Express Data Loader, choose File Transfer Settings.
6. Select Upload SFTP user public key. See Configuring SFTP Keys for more information.

28.1.2.3.1 Enabling SSH Communication with Express Data

Loader

This section describes how to set up the <known hosts> file in SAP Integration Suite to enable SSH
Communication with Express Data Loader in SAP SuccessFactors Incentive Management.

Procedure

1. In SAP Integration Suite, choose Monitor > Integrations > Manage Security > Connectivity Tests.
2. Select the SSH tab.
3. Enter the Express Data Loader (XDL) Host. (You can find this information in Express Data Loader > File
Transfer Settings.)

Incentive Management Admin Design Guide

392 PUBLIC Integration
4. Set Port to 9092. You can also use the value specified in Express Data Loader > File Transfer Settings.
5. Select None for Authentication.
6. Choose Send.
7. Choose Copy Host Key when you get the response.
8. Navigate to Monitor > Integrations > Manage Security > Security Material and download the <known
hosts> file.
9. Add the content that you copied from the Connectivity Test to the end of the file.

 Note

Each tenant host key needs to be added to <known hosts> file. The simplest way to get the Host Key is
to use the Test Connectivity functionality available in SAP Integration Suite.

10. Select Add > Known Hosts (SSH) and upload the edited file.

28.1.2.3.2 Storing User Credentials in the SAP Integration

Suite Security Material

For Secure SAP S/4HANA OData API Calls, OData API user credentials must be securely stored in the SAP
Integration Suite Security Material.

Procedure

1. In SAP Integration Suite, choose Monitor > Integrations > Manage Security > Security Material.
2. Choose Create > User Credentials.

Field Value

Name Enter any name

Description Enter Description

Type User Credentials

User Enter S/4HANA Username

Password Enter S/4HANA Username password

Repeat password Enter S/4HANA Username password

3. Choose Deploy.

Incentive Management Admin Design Guide

Integration PUBLIC 393
28.1.2.3.3 Copying the Integration Package to SAP
Integration Suite Tenant

SAP Integration Suite web interface is used to access and manage the integration flows that are configured in
integration suite tenant.

Procedure

1. Go to the SAP Integration Suite tenant for which you want to set up the integration content.
2. Choose Discover > Integration and find the SAP S/4HANA Integration with SAP SuccessFactors
Incentive Management package.
3. Choose Copy. By selecting the Copy option, the package will automatically be added to the list in Designed
> Integrations.

28.1.2.3.4 Setting Up the Integration Configuration

Controller

The Integration Configuration Controller allows you to define settings for each Integration Flow so you can
control the behavior of the integration.

Procedure

1. In the SAP Integration Suite tenant, go to Design > Integrations.

2. Select the SAP S/4HANA Integration with SAP SuccessFactors Incentive Management package. See
Copying the Integration Package to SAP Integration Suite Tenant [page 394].
3. Choose Artifacts, select Actions and choose Configure to define the integration flow settings.

Incentive Management Admin Design Guide

394 PUBLIC Integration
28.1.3 Timer Setup

In SAP Cloud Integration service, you can configure the integration flow to run once, daily, every 12 hours, and
so on.

By default, the integration flow will run every 10 minutes.

See Define a Timer Start Event for an overview.

28.1.4 Receiver Setup

Receiver setup involves the following:

• Setting Up Express Data Loader (XDL) Receiver for SFTP Connection [page 395]
• SAP S/4HANA OData Receiver [page 396]
• Post Execution Flow [page 398]
• Post Execution Assignee Flow [page 398]
• Notification Extension Flow [page 399]
• SAP S/4HANA RFC Receiver [page 399]

28.1.4.1 Setting Up Express Data Loader (XDL) Receiver for

SFTP Connection

The Express Data Loader (XDL) receiver in SAP SuccessFactors Incentive Management enables you to
configure the SFTP connection.

Incentive Management Admin Design Guide

Integration PUBLIC 395
Procedure

To add the target system details in SAP Cloud Integration service, perform the following:

1. Address: Enter the SFTP host and SFTP port for your Incentive Management instance. (You can find this in
Express Data Loader > File Transfer Settings.).
2. User Name: Enter the username for the Express Data Loader SFTP connection. (You can find this in
Express Data Loader > File Transfer Settings.).
3. Private Key Alias: Enter the alias of the SSH key pair generated in SAP Integration Suite.

See SFTP Receiver Adapter for an overview.

28.1.4.2 SAP S/4HANA OData Receiver

SAP S/4HANA OData receiver enables you to configure the OData connection.

Procedure

In SAP Cloud Integration service, configure the following settings:

• S/4HANA URL: Enter the SAP S/4HANA API URL. For Example: https://testHana-
api.s4hana.ondemand.com. Ffor more details, check Sales Orders OData API documentation or Billing
Documents OData api documentation. https://api.sap.com/api/API_SALES_ORDER_SRV/overview
• Proxy Type: Specify if Internet or On-Premise. (By default it is Internet.)
• Authentication: Choose Authentication type for S/4HANA OData API. (By Default it is Basic.)
• Credential Name: Enter the Name of the User Credentials saved in the Security Material of SAP Integration
Suite
• Additional Fields: The flow doesn’t read all the attributes available from the SAP S/4HANA OData service
but restricts it to the relevant ones for SAP SuccessFactors Incentive Management. In case you need

Incentive Management Admin Design Guide

396 PUBLIC Integration
 additional fields from the same Sales Order Item, which are not selected already, you can add them here.
For example: PlantRegion, PlantCity, and so on, which will be added into the payload, and you will be able to
use them in the extended flow.
• Additional Expand: Enter the name of the relation from which you would like to select fields (e.g.
",to_BillingPlan")
• Additional Filter –OData connector has an unchangeable part of the filter that filters already processed
records by checking if Sales Order/Billing Document change date is after the date of last synchronized
transaction. There is also a changeable part of the filter where you can add any condition based on
your business needs. By default for Billing Documents flow, it is empty and for Sales Order flow it is
to_SalesOrder/SalesOrderType eq 'OR' and SalesOrderItemCategory eq 'TAN'. This means the flow will
sync just Sales Order Items with type ‘OR’ and category ‘TAN’.
• Additional OrderBy: Use this configuration only if change date time field only contains the date without
time. All flows are already ordered by change date time by default. (e.g. ",SalesOrder")
• Page Size: You can configure how many records must be retrieved from SAP S/4HANA OData in one call.
System performance can be affected based on this value. If the number is too small, the flow run will last
longer, but if it is too large, you may get an error from SAP S/4HANA RAISE_SHORTDUMP with status 500
because the load is too large. The optimal number is different for each instance. We recommend starting
with 4000.
• Timeout (in min): This indicates the duration to wait for a response from OData. By default this is set to 10
minutes.

See SFTP Receiver Adapter for an overview.

Incentive Management Admin Design Guide

Integration PUBLIC 397
28.1.4.3 Post Execution Flow

SAP Cloud Integration allows you to extend the capabilities of the standard integration content provided by
SAP. This approach allows you to implement specific integration scenarios relevant to your business use
case without changing the content provided by SAP. Post execution flow will be called if it is enabled in the
configuration.

You can edit the address of the Process Direct call in SAP Cloud Integration if needed.

For more information about the Integration Flow Extension concept, see Integration Flow Extension.

Also, see SFTP Receiver Adapter for an overview.

28.1.4.4 Post Execution Assignee Flow

Post execution assignee flow will be called if it is enabled in the configuration. You can edit the address of the
Process Direct call in SAP Cloud Integration if needed.

For more information about the Integration Flow Extension concept, see Integration Flow Extension.

Also, see SFTP Receiver Adapter for an overview.

Incentive Management Admin Design Guide

398 PUBLIC Integration
28.1.4.5 Notification Extension Flow

The Notification Extension Flow is called only if the flow is configured to send email notifications by using
extension flow. You can edit the address of the Process Direct call in SAP Cloud Integration if needed.

See SFTP Receiver Adapter for an overview.

28.1.4.6 SAP S/4HANA RFC Receiver

Target RFC must be added after it is included as BTP RFC Destination set.

To add the target RFC after it was added as BTP RFC Destination set:

For Adapter type, choose the RFC from the drop down and for Destination, enter the destination name from
BTP Destinations page.

28.1.5 More Options (Partner Functions)

Since SAP S/4HANA partner functions can be different for different tenants, this option allows you to configure
the partner functions for Ship to customer, Employee, Bill to customer, and Others To. You can also configure
in which mode the flow should run, whether it should call extended flows, the Initial Start Date and theSAP
SuccessFactors Incentive Management Tenant ID.

Incentive Management Admin Design Guide

Integration PUBLIC 399
Provide the following details in SAP Cloud Integration:

• Assignee Partner Function: Enter the Sales Employee Partner Function.

• BillTo Partner Function: Enter the Partner Function which you want to map to BillTo.
• Initial Start Date: Edit to change the date to indicate from when to synchronize data on the first run.
• Is Assignee Flow Extended: Change value to true to call your extension flow for transaction assignees
mapping.
• Is Main Flow Extended: Change to true to call your extension flow for transaction mapping.
• Last Processed Time Global Variable: The SAP Integration Suite variable is used to store information about
the last synced item. Variable reflects the exact date and time when the last synced order is last updated
in SAP S/4HANA. You can define variable names here. If you have more than one flow instance running
in the same Integration Suite instance (for example, you have one flow run for test instance and other for
production), you must define the unique variable name for each flow instance here.
• OtherTo Partner function: Enter the Partner Function which you want to map to OtherTo.
• SAP SF Incentive Management Tenant ID: Enter the 4 letter Tenant ID of SAP SuccessFactors Incentive
Management.
• ShipTo Partner Function: Enter the Partner Function that you want to map to ShipTo.
• Transactions with Assignee: You can choose if the flow should synchronize relations with assignees or not
by entering true or false.
• Use Email Notification Extension Flow: If you would like to use extension flow provided
in this package for email notification, set this configuration value to true. Prerequisite for
enabling the notification extension flow is that the integration flow Send Email Notification
for SAP SuccessFactors Incentive Management integration is configured and deployed.
By default, notification extension is not used, and this field value is set to false.

• Additionally for the Replicate Products from SAP S/4HANA integration flow, provide the following details:
• Category tree name: Enter the category tree name that already exists in SAP SuccessFactors Incentive
Management.

Incentive Management Admin Design Guide

400 PUBLIC Integration
 • Default Category: Enter the category name that already exists inSAP SuccessFactors Incentive
Management. This value will be used for Products without Product Hierarchy in S/4HANA and those
products will be replicated to SAP SuccessFactors Incentive ManagementClassifiers in the category
defined for this field.
• Product description language: Since the product description in S/4HANA is language dependent, it
will be replicated to SAP SuccessFactors Incentive Management based on the language value in this
configuration field.

28.1.6 Deploying the Integration Flow

After flow is configured, it is ready to be deployed.

In SAP Cloud Integration service, select Actions in the flow and choose Deploy.

A message stating that the flow is triggered for deployment is displayed. After the flow is deployed, execution
starts after 10 minutes, if you configured the schedule to run on each 10 minutes.

See Working with Intergration Packages for an overview.

Incentive Management Admin Design Guide

Integration PUBLIC 401
Related Information

Timer Setup [page 395]

28.1.7 Logging and Monitoring Integrations

SAP Integration Suite provides a web-based monitoring UI that allows you to check the status of messages and
integration content artifacts for a tenant cluster.

Procedure

To monitor the integration flow in SAP Integration Suite, perform the following:

1. In SAP Integration Suite, choose Monitor > Integrations > Monitor Message Processing > All Artifacts .
2. From the Artifact list, select the name of the chosen flow (Replicate Sales Order Items from SAP S/4HANA
or Replicate Billing Documents from SAP S/4HANA)
3. A list of Messages with statuses will be displayed. Each message represents one execution of the flow.
Make sure that status of the message is Completed
4. Select the first message from the list. It represents the last execution of the flow. Scroll down to Custom
Headers and check the Express Data Loader (XDL) transaction file names and Number of processed Sales
Order/Billing Document Items.

5. Scroll to Attachments and if some Sales Order/ Billing Document items were skipped, the Skipped Sales
Order Items file will be displayed.

6. Go to SAP SuccessFactors Incentive Management > Express Data Loader (XDL) > Jobs and check the
status of the job with the name from step 4. Make sure that Status is Success and the number of Success
statuses should be the same as number of processed items from step 4.

Incentive Management Admin Design Guide

402 PUBLIC Integration
See Monitor Integrations for an overview.

28.1.8 Error and Recovery

This section provides information on how to handle integration flow errors and exceptions.

Data Validation Errors

Express Data Loader (XDL) in SAP SuccessFactors Incentive Management validates the data and if there are
any failures, you can download the file with errors from the user interface.

Exceptions

If there are any errors, you must check the pipeline in SAP SuccessFactors Incentive Management and fix the
system data (Event Type, Currency etc.) or the stage data (in Transaction itself) before rerunning the failed
batch transfer again. There is no need to fetch the data again from SAP S/4HANA since the data is already in
the stage tables.

Reprocess Data Replication

In case of Exceptions in the flow, the local variable of the last processed record will not be updated. When
the Integration flow is re-run, it fetches all the records modified since the last successful run. When the flow
needs to be started from the Initial Start Date, you must remove the variable with the last processed record
timestamp (which has a configurable name).

28.1.9 Email Notification Flow Setup

In the SAP S/4HANA Integration with SAP SuccessFactors Incentive Management package, an additional
integration flow Send Email Notification for SAP SuccessFactors Incentive Management integration is
provided, which is meant to be used for sending email notification to the other two integration flows in the
package (Replicate Sales Order Items from SAP S/4HANA and Replicate Billing Document Items from SAP
S/4HANA).

Incentive Management Admin Design Guide

Integration PUBLIC 403
Prerequisites

• You must provide the email server details, which will be used to send notifications.
• You must configure the chosen integration flow to call the notification extension flow.

Notification Content

The Send Email Notification for SAP SuccessFactors Incentive Management integration flow sends an
email when the flow execution fails the first time.

• Execution Status: Status can be Failed or Successful.

• Message ID: Based on this information, you can search Messages in SAP Integration Suite > Monitor
Message Processing.
• If the execution fails, the email contains error details. If the Execution was successful, the email contains
the number of processed transactions.

The Notification flow sends an email only when the execution status is changed from the last execution. Based
on that, the configured email receiver will get one email when flow starts falling and the next email when the
flow starts passing without any error.

Notification Flow Configuration

Configure the following in SAP Cloud Integration:

Sender: In the Address field, the Process Direct address is displayed, and it can be changed if it is already
changed for the main flow. You must enter the same value as you did in the main flow in Configure > Receiver >
NotificationExtensionFlow > Address.

Receiver: You can configure all the email settings related to the email server and email receivers.

See Configure the Mail Receiver Adapter for more information.

Incentive Management Admin Design Guide

404 PUBLIC Integration
More Options

The Notification Extension Flow uses the SAP Integration Suite global variable to store the status of the last
flow execution. Based on the status value, the Notification Flow decides if the notification email should be
sent or not. Notification is sent only if the status changes. If you have two instances of this flow on the same
Integration Suite tenant, you need to change the name of the variable.

28.1.10 Difference Between SAP S/4HANA and SAP

SuccessFactors Incentive Management Data Models

This section highlights some differences in SAP S/4HANA sales orders and billing documents comparison
toSAP SuccessFactors Incentive Management transactions and explains the chosen mapping approach in the

Incentive Management Admin Design Guide

Integration PUBLIC 405
flows. You may want to adjust the mapping using the optional Post Processing step if the default approach does
not fit your business needs and situation.

SAP S/4HANA Sales Document and SAP SuccessFactors Incentive

Management Identifiers

The flow maps SAP S/4HANA sales document items to SAP SuccessFactors Incentive Management
transactions. The below table provides an explanation of how the identifying fields of the Incentive
Management transactions are mapped.

Transaction Attribute S/4HANA Attribute Description

ORDERID OrderType + CreationDate + SalesOr- The SAP S/4HANA order id is con-

derID catenated with the order type and the
creation date to ensure that the result-
ing id is always unique. The default SAP
S/4HANA Sales order id is written to
a generic attribute to support finding
the transaction based on the SAP S/
4HANA sales order id.

LINENUMBER SalesOrderItem -

SUBLINENUMBER - Not used. In an SAP S/4HANA sales

document, the LINENUMBER identifies
the item.

EVENTTYPEID SalesOrderType The SAP SuccessFactors Incentive

Management event type is set to the
SAP S/4HANA Sales Order Type. A pre-
requisite for this approach is that all
relevant SAP S/4HANA order types are
created in the Incentive Management
configuration as event types. You must
evaluate if this approach fits to your
project needs. Alternative approaches
are:

• EVENTTYPEID = SalesOrderItem-
Category (The item category de-
fines how an order item is proc-
essed in SAP S/4HANA.)
• EVENTTYPEID = SalesOrderType +
SalesOrderItemCategory
• Value mapping of the relevant SAP
S/4HANA attribute to the existing
SF Incentive Management event
type ids.

Incentive Management Admin Design Guide

406 PUBLIC Integration
SAP S/4HANA Order Types and Item Categories

In SAP S/4HANA sales documents, these attributes mainly control how a sales document item is processed
and. what data it contains.

• Sales Document Type

• Item Category

The default query in the flow reads these sales document items:

• Sales Orders: Order Type = OR, all item categories

• Billing Documents

You must evaluate if this fits your business needs and adjust the query as needed.

Order Item Hierarchy

An SAP S/4HANA sales document can contain an item hierarchy tree that consists of several levels. You must
determine which hierarchy levels / item categories to transfer to SAP SuccessFactors Incentive Management,
if you are using an item hierarchy. Otherwise, you may transfer the same SAP S/4HANA revenue several times
toSAP SuccessFactors Incentive Management causing wrong compensation calculations.

SAP S/4HANA Pricing Conditions

The integration flow by default maps these SAP S/4HANA currency amounts from S/4HANA to SAP
SuccessFactors Incentive Management:

• Sales Orders
• Billing Documents
• Sales Contracts
• Sales Quotations
• Service Contracts

You must evaluate if this flow fits your business needs and adjust the transformation to include dedicated SAP
S/4HANA pricing conditions as needed.

28.1.11 Integration with SAP S/4HANA Cloud and S/4HANA

Private Cloud - Glossary

The following table describes the terms and abbreviations used in this section and related topics.

Incentive Management Admin Design Guide

Integration PUBLIC 407
Term Description

Flow Automated workflow in SAP Integration Suite that is used to

synchronize data between multiple applications or services.

Run Execution of the integration flow.

S/4HANA Sales Entity Sales data transferred by flow depending on the chosen flow,
for example, Sales Order.

Timer-driven integration Type of integration setup where data transfer or synchroni-

zation occurs at specific time intervals.

Express Data Loader (XDL) A component of SAP SuccessFactors Incentive

Management. See Express Data Loader for details.

Related Information

Integration Flow Prerequisites [page 387]

28.2 Integration with SAP IdP

This section describes the integration between SAP SuccessFactors Incentive Management, Identity
Authentication, and Identity Provisioning. This integration allows seamless login to users who are synced
between these applications as well as user provisioning.

SAP SuccessFactors Incentive Management supports integration with the following two applications:

• Identity Authentication - In this application, you can create different types of SAP SuccessFactors Incentive
Management users. Depending on the user synchronization approach, this application can behave either
as the source or target system.
• Identity Provisioning - In this application, you can start the user sync job, and monitor the synchronization
process.

URL

You will be provided with the SAP IdP based SAP SuccessFactors Incentive Management URL. This URL
prompts users to enter their user ID and password via IdP and redirects users to SAP SuccessFactors Incentive
Management

User Provisioning

The integration supports user provisioning both in the bottom-up and top-down user synchronization
approach. In order to enable this, you need to define target and source systems in your environment.

Incentive Management Admin Design Guide

408 PUBLIC Integration
Depending on the user synchronization approach, the target system can either be SAP SuccessFactors
Incentive Management (top-down approach) or Identity Authentication (bottom-up approach).
To learn more about the integration between SAP IdP and the sales performance management solutions in the
SAP SuccessFactors portfolio, see Sales Performance Management Single Sign-On Administrator Guide.

28.2.1 Bottom-Up User Synchronization with Identity

Authentication

Introduction

This integration enables you to connect SAP SuccessFactors Incentive Management to the Identity
Authentication service to leverage the following benefits:

• Centralized Identity Management

• Single Sign On (SSO)
• Multi Factor Authentication (MFA)

Integration uses a bottom-up approach. Users are created in SAP SuccessFactors Incentive Management and
replicated to Identity Authentication. This is a one-way provisioning. No user information is replicated back
from Identity Authentication to SAP SuccessFactors Incentive Management.

The user administrator mainly works in SAP SuccessFactors Incentive Management. Users are maintained
inSAP SuccessFactors Incentive Managementand replicated to Identity Authentication.

A typical sequence of steps is as follows:

1. The SAP SuccessFactors Incentive Managementuser administrator creates new business user in Incentive
Management.
2. The scheduled read job in Identity Provisioning reads the new user from SAP SuccessFactors Incentive
Managements and creates a new user in Identity Authentication.
3. The Business User receives an onboarding email notification from Identity Authentication.
4. The E-Mail contains a link to the Identity Authentication User Profile. The Business User clicks on it and
sets his/her password in Identity Authentication.
5. The Business User logs on to SAP SuccessFactors Incentive Management. The user will access the
Incentive Management SSO URL.
6. SAP SuccessFactors Incentive Management redirects to the Identity Authentication login page where the
business user logs in.
7. Identity Authentication redirects to the SAP SuccessFactors Incentive Management welcome page on
successful login.

Bottom-Up Integration SAP SuccessFactors Incentive Management and Identity Authentication

Incentive Management Admin Design Guide

Integration PUBLIC 409
28.2.1.1 SAP SuccessFactors Incentive Management User
Management - Overview

SAP SuccessFactors Incentive Management has two different types of users:

Incentive Management Portal Users Example: Participants

Managed in Incentive Management Portal > User

Administration

Incentive Management Admin Users Example: Administrators that configure SAP SuccessFactors
Incentive Management

Managed in Incentive Management Admin > Manage Setup

>Security > Users

There are different ways to create users in SAP SuccessFactors Incentive Management:

• Via the UI option available in Incentive Management Portal and Incentive Management Admin
(mentioned in the section above).
• Via remote APIs.

Incentive Management Admin Design Guide

410 PUBLIC Integration
• Via File Upload, for example, using Express Data Loader..
• Each Participant record automatically creates a new Incentive Management Portal user record.
• Each Incentive Management Admin user record automatically creates a Incentive Management Portal user
record.

The following image explains how the different records are linked with each other:

28.2.1.2 Sample Integration Scenarios and Configuration

Details

This topic lists some sample integration scenarios between SAP SuccessFactors Incentive Management and
the Identity Authentication service with the required configuration details.

Scenario 1: Single-Sign-On via Identity Authentication for All Incentive

Management Admin Users

To enable Single-Sign-On via Identity Authentication for all Incentive Management Admin users, it is sufficient
to replicate the Incentive Management Portal users. Replication of Incentive Management Admin users is not
required. Replication of user to group/role assignments is also not required.

Incentive Management Admin Design Guide

Integration PUBLIC 411
Replication of Incentive Management Portal users:

The configuration to replicate Incentive Management Portal in Identity Provisioning is as follows:

We need one source system in Identity Provisioning for Incentive Management Portal that reads the Portal
users and one target system for Identity Authentication to replicate the users into Identity Authentication.

Scenario 2: Enable Multi Factor Authentication for All Incentive Management

Admin Users

For this scenario, the user replication setup is the same as described in the Scenario 1 above. The
configuration of Multi Factor Authentication is done completely in Identity Authentication. See Configure
Risk-Based Authentication for an Application for details on how to configure MFA in Identity Authentication.

Incentive Management Admin Design Guide

412 PUBLIC Integration
Scenario 3: Enable Multi Factor Authentication for Incentive Management
Admin Users

Let’s assume the goal is to enforce MFA for Incentive Management Admin Users but not for all users, e.g. not
for participants. Identity Authentication supports this case via “risk-based authentication”. One can define a
rule that all users with the role “Administrator” need to present a second factor when logging in.

The replication of Incentive Management Portal and Incentive Management Admin users plus groups will now
look like this:

Additionally:

• Incentive Management Admin User information is replicated

• Role/Group assignment both for the Incentive Management Portal user and the Incentive Management
Admin Users are replicated and available in Identity Authentication.

Identity Authentication would decide, for example, based on the group “Administrator” that the user has
presented a second factor to authenticate. Therefore, Identity Authentication needs to be aware of the group
assignments done in Incentive Management Admin.

The configuration to replicate Incentive Management Portal and Incentive Management Admin users plus
groups in Identity Provisioning for this scenario is as follows:

Incentive Management Admin Design Guide

Integration PUBLIC 413
One needs an additional source system on Identity Provisioning for the Incentive Management Admin Users.
It is linked to the same target system for Identity Authentication. The SCIM standard defines two resources,
Users and Groups. For this scenario, both resources Users and Groups are needed.

See Configuration to Replicate Incentive Management Portal Users [page 414] and Configuration to Replicate
Administration Users [page 431] for details on configuring User Replication for the different scenarios that are
illustrated in this topic.

28.2.1.3 Configuration to Replicate Incentive Management

Portal Users

Configuration in SAP SuccessFactors Incentive Management

Create a user in Incentive Management Portal with role as Portal Admin and set a password. Identity
Provisioning will call the SAP SuccessFactors Incentive Management SCIM API with this user.

 Note

It is recommended to create a separate user for this integration instead of reusing an existing one. A
separate user would mean better separation of concerns and better traceability in case of issues.

Configuration in Identity Provisioning

Source System for Incentive Management Portal

The SAP Note 2999357 contains a sample configuration for the source system that one can upload
to Identity Provisioning. Please download the attachment Bottom-Up-Source-SAP-Commissions-Portal-
V3.json. The provided configuration is a recommendation and is optional to use.

Incentive Management Admin Design Guide

414 PUBLIC Integration
The type of the source system to be created is SCIM System. Refer to the related Identity Provisioning
documentation in: SCIM System and Add a System.

 Note

Do not use the existing System Type “SAP SuccessFactors Incentive Management”.This system type only
works with an older version of the SAP SuccessFactors Incentive Management SCIM API.

On the Source System Creation page, select the Define from File option and upload the file Bottom-Up-
Source-SAP-Commissions-Portal-V3.json here. The source system is now populated with the values
from this file. Then, perform the following changes:

Tab Details

Provide a system name.

Tab Transformations

In case you don’t require groups and user to group assignments to be transferred, you can discard them using
the transformation expression “ignore” as explained in Transformation Expressions.

Tab Properties

Set these properties:

Property Name Value Comment

ips.trace.failed.entity.content true Both values true and false are possible.

Value true gives you better analysis op-
tions in case of errors. A potential setup
is, for e.g., to use true in the Test envi-
ronment and false in Production.

Password < Password assigned in Portal> Enter the password you assigned the
portal user.

URL https://<SAP SuccessFactors Incentive Replace <SAP SuccessFactors

Management Tenant URL>/Callidus- Incentive Management Tenant URL>
Portal/services/v3/scim with the URL of your Incentive Manage-
ment tenant.

User < Portal user id of the user created Enter the portal user name created be-
above > fore.

Target System for SAP Identity Authentication

Create a target system for SAP Identity Authentication if not already there. See Identity Authentication.

The SAP Note 2999357 contains a sample configuration for the target system that one can upload
to Identity Provisioning. Please download the attachment Bottom-Up-Target-SAP-IAS-V3.json. The
provided configuration is just a proposal. It is optional to use it.

On the Target System Creation page, use the Define from File option and upload the file Bottom-Up-Target-
SAP-IAS-V3.json here. The target system is now populated with the values from this file. Then, perform the
following changes:

Tab Details

Provide a system name.

Incentive Management Admin Design Guide

Integration PUBLIC 415
Add the source system for Incentive Management Portal that you created in “Source Systems”.

Tab Properties

Set the properties as described in Identity Authentication.

28.2.1.4 Setting Up User Synchronization from SAP Incentive

Management to Identity Authentication Using
Identity Authentication SCIM v2

If you are using Identity Authentication solely for SAP Incentive Management, you will have user sync
configured during tenant provisioning, with the current default using Identity Authentication SCIM v1.

If you are using multiple SAP products sharing the same Identity Authentication, you must decide how to
configure user sync. If Incentive Management is chosen as the source system, follow the steps in this topic to
manually configure the user sync.

 Note

Identity Authentication SCIM v1 does not make groups in user properties read-only, which causes issues
when deleting groups during the Incentive Management sync job. To resolve this, Identity Provisioning
transformations with Identity Authentication SCIM v2, which sync groups through the group resource must
be used. The assingGroup function in Identity Provisioning transformations will sync Embedded Analytics
groups to Identity Authentication. To identify the SCIM version, check the ias.api.version property in
the target system.

If another source system is already enabled, syncing will overwrite user properties from the target system
with values from Incentive Management. To avoid this, remove property mappings or set 'ignore': true on
those mappings. For attribute patching, refer to the Patched and Merged Attributes documentation and
adjust the transformation accordingly.

Procedure

1. Create the OIDC Application in Identity Authentication. Next, in Incentive Management, create the Service
Account record with "IPS-SCIM-{clientIdFromIASApplication}" as the Display Name. This is
used for communication between Identity Provisioning and Incentive Management. See Service Account
Authentication for more information on how to create OIDC application and Service Accounts.
• Assign the Incentive Management Admin group to this service account that has all the permissions
to work with Users and Groups (for example, Administrator group; this group may have other
permissions too which are not required).
• Assign Sales Portal Administrator as Role to this service account.
• Save the clientId and clientSecret.
2. Create the Identity Authentication system user that will be used for communication between Identity
Authentication and Identity Provisioning. See Add New Administrators for more information on how to
create system users.

Incentive Management Admin Design Guide

416 PUBLIC Integration
 • Assign Manage Users and Manage Groups as Roles to this system service account.
• Save the clientId and clientSecret.
3. Go to Identity Authentication > Groups and get group IDs for the following groups: APP_SCAN, APP_SCAI,
ADMINISTRATOR_COMM-SCAN, AUTHENTICATED_COMM-SCAN and ADMINISTRATOR_COMM-SCAI.
4. Go to IAS Applications and search for Sales Performance Home to find the Incentive Management SAML
application. Click on that application and get the Application ID information.
5. Create two Source systems and one Target system in Identity Provisioning.

Incentive Management Admin Design Guide

Integration PUBLIC 417
 Portal Source 1. Save the following JSON object in the JSON file:

 Sample Code

{
"connectorTypeString": "SALESCLOUD_COMM",
"accessMode": "READ",
"destinationName": "",
"alias": "This is a source system for Incentive
Management portal users",
"gitAllowedExpressions": [],
"gitDisallowedExpressions": [],
"emailSubscribers": [],
"name": "IncentiveManagement_SOURCE_PORTAL",
"state": "ENABLED",
"systemManagementType": "CUSTOMER_MANAGED",
"properties": {
"Authentication": "BasicAuthentication",
"ips.delta.read": "enabled",
"ips.full.read.force.count": "3",
"ips.trace.failed.entity.content": "true",
"OAuth2TokenServiceURL": "$IAS_BASE_URL$/
oauth2/token",
"ProxyType": "Internet",
"Type": "HTTP",
"URL": "$INCENTIVE_MANAGEMENT_BASE_URL$/
usersvc/portal",
"User": "$SERVICE_ACCOUNT_CLIENT_ID$"
},
"encryptedProperties": {
"Password": "$SERVICE_ACCOUNT_CLIENT_SECRET$"
},
"automaticOutboundCertificateRenew": false,
"transformationChanged": false,
"readTransformationChanged": false,
"writeTransformationChanged": false,
"fromImport": false,
"transformation": {
"user": {
"mappings": [
{
"sourcePath": "$.userName",
"targetPath": "$.userName",
"correlationAttribute": true
},
{
"sourcePath": "$.id",
"targetVariable":
"entityIdSourceSystem"
},
{
"sourcePath": "$.name",
"optional": true,
"targetPath": "$.name"
},
{
"sourcePath": "$.userType",
"optional": true,
"targetPath":
"$.incentiveManagementUserType"
},
{
"sourcePath": "$.displayName",

Incentive Management Admin Design Guide

418 PUBLIC Integration
 "optional": true,
"targetPath": "$.displayName"
},
{
"sourcePath": "$.active",
"optional": true,
"targetPath": "$.active"
},
{
"sourcePath": "$.groups",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.groups"
},
{
"sourcePath": "$.emails",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.emails"
},
{
"sourcePath": "$.emails[?
(@.primary== true)].value",
"optional": true,
"correlationAttribute": true
},
{
"sourcePath": "$.schemas",
"preserveArrayWithSingleElement":
true,
"targetPath": "$.schemas"
},
{
"sourcePath": "$.locale",
"optional": true,
"targetPath": "$.locale",
"functions": [
{
"function": "substring",
"beginIndex": 0,
"endIndex": 2
},
{
"function":
"toUpperCaseString"
}
]
},
{
"constant":
"$IM_SAML_IAS_APPLICATION_ID$",
"targetPath": "$.applicationId"
}
]
},
"group": {
"mappings": [
{
"sourcePath": "$.displayName",
"optional": true,
"targetPath": "$.displayName",

Incentive Management Admin Design Guide

Integration PUBLIC 419
 "functions": [
{
"function": "concatString",
"prefix": "COM_SLS_"
}
]
},
{
"sourcePath": "$.id",
"targetVariable":
"entityIdSourceSystem"
},
{
"sourcePath": "$.description",
"optional": true,
"targetPath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['description']"
},
{
"sourcePath": "$.members[*].value",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.members[?
(@.value)]"
}
]
}
},
"gitFetchAllowed": false
}

2. Replace everything between $$ with the values related to your tenant:

• Replace $IAS_BASE_URL$ with your IAS url.

• Replace $INCENTIVE_MANAGEMENT_BASE_URL$ with your Incentive Management
tenant url.
• Replace $SERVICE_ACCOUNT_CLIENT_ID$ with OIDC client id from the step 1.
• Replace $SERVICE_ACCOUNT_CLIENT_SECRET$ with OIDC client secret from the
step 1.
• Replace $IM_SAML_IAS_APPLICATION_ID$ with application id from the step 4.

3. Click Create Source System and upload the JSON file.

4. Save the updates.

Incentive Management Admin Design Guide

420 PUBLIC Integration
 Admin Source 1. Save the following JSON object in the JSON file:

 Sample Code

{
"connectorTypeString": "SALESCLOUD_COMM",
"accessMode": "READ",
"destinationName": "",
"alias": "This is a source system for Incentive
Management admin users",
"gitAllowedExpressions": [],
"gitDisallowedExpressions": [],
"emailSubscribers": [],
"name": "IncentiveManagement_SOURCE_ADMIN",
"state": "ENABLED",
"systemManagementType": "CUSTOMER_MANAGED",
"properties": {
"Authentication": "BasicAuthentication",
"ips.delta.read": "enabled",
"ips.full.read.force.count": "3",
"ips.trace.failed.entity.content": "true",
"OAuth2TokenServiceURL": "$IAS_BASE_URL$/
oauth2/token",
"ProxyType": "Internet",
"Type": "HTTP",
"URL": "$INCENTIVE_MANAGEMENT_BASE_URL$/
usersvc/admin",
"User": "$SERVICE_ACCOUNT_CLIENT_ID$"
},
"encryptedProperties": {
"Password": "$SERVICE_ACCOUNT_CLIENT_SECRET$"
},
"automaticOutboundCertificateRenew": false,
"transformationChanged": true,
"readTransformationChanged": false,
"writeTransformationChanged": false,
"fromImport": false,
"transformation": {
"user": {
"mappings": [
{
"sourcePath": "$.userName",
"targetPath": "$.userName",
"correlationAttribute": true
},
{
"sourcePath": "$.id",
"targetVariable":
"entityIdSourceSystem"
},
{
"sourcePath": "$.name",
"optional": true,
"targetPath": "$.name"
},
{
"sourcePath": "$.userType",
"optional": true,
"targetPath":
"$.incentiveManagementUserType"
},
{
"sourcePath": "$.displayName",

Incentive Management Admin Design Guide

Integration PUBLIC 421
 "optional": true,
"targetPath": "$.displayName"
},
{
"sourcePath": "$.active",
"optional": true,
"targetPath": "$.active"
},
{
"sourcePath": "$.groups",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.groups"
},
{
"sourcePath": "$.emails",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.emails"
},
{
"sourcePath": "$.emails[?
(@.primary== true)].value",
"optional": true,
"correlationAttribute": true
},
{
"sourcePath": "$.schemas",
"preserveArrayWithSingleElement":
true,
"targetPath": "$.schemas"
},
{
"sourcePath": "$.locale",
"optional": true,
"targetPath": "$.locale",
"functions": [
{
"function": "substring",
"beginIndex": 0,
"endIndex": 2
},
{
"function":
"toUpperCaseString"
}
]
},
{
"constant":
"$IM_SAML_IAS_APPLICATION_ID$",
"targetPath": "$.applicationId"
}
]
},
"group": {
"mappings": [
{
"sourcePath": "$.displayName",
"optional": true,
"targetPath": "$.displayName",

Incentive Management Admin Design Guide

422 PUBLIC Integration
 "functions": [
{
"function": "concatString",
"prefix": "COM_COM_"
}
]
},
{
"sourcePath": "$.id",
"targetVariable":
"entityIdSourceSystem"
},
{
"sourcePath": "$.description",
"optional": true,
"targetPath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['description']"
},
{
"sourcePath": "$.members[*].value",
"preserveArrayWithSingleElement":
true,
"optional": true,
"targetPath": "$.members[?
(@.value)]"
}
]
}
},
"gitFetchAllowed": false
}

2. Replace everything between $$ with the values related to your tenant:

• Replace $IAS_BASE_URL$ with your IAS url.

• Replace $INCENTIVE_MANAGEMENT_BASE_URL$ with your Incentive Management
tenant url.
• Replace $SERVICE_ACCOUNT_CLIENT_ID$ with OIDC client id from the step 1.
• Replace $SERVICE_ACCOUNT_CLIENT_SECRET$ with OIDC client secret from the
step 1.
• Replace $IM_SAML_IAS_APPLICATION_ID$ with application id from the step 4.

3. Click Create Source System and upload the JSON file.

4. Save the updates.

Incentive Management Admin Design Guide

Integration PUBLIC 423
 Target 1. Save the following JSON object in the JSON file:

 Sample Code

{
"connectorTypeString": "SAP_CLOUD_IDENTITY",
"accessMode": "WRITE",
"destinationName": "",
"alias": "This is a IAS target system for
Incentive Management application",
"relatedSystems": [
"IncentiveManagement_SOURCE_PORTAL",
"IncentiveManagement_SOURCE_ADMIN"
],
"gitAllowedExpressions": [],
"gitDisallowedExpressions": [],
"emailSubscribers": [],
"name": "IncentiveManagement_IAS_TARGET",
"state": "ENABLED",
"systemManagementType": "CUSTOMER_MANAGED",
"properties": {
"Authentication": "BasicAuthentication",
"ias.api.version": "2",
"ias.content.type": "application/scim+json",
"ias.support.patch.operation": "true",
"ias.user.unique.attribute": "userName",
"ips.delete.existedbefore.entities": "false",
"ips.failed.request.retry.attempts": "2",
"ips.failed.request.retry.attempts.interval":
"60",
"ips.full.read.force.count": "3",
"ips.trace.failed.entity.content": "true",
"ProxyType": "Internet",
"Type": "HTTP",
"URL": "$IAS_BASE_URL$",
"User": "$SYSTEM_USER_CLIENT_ID$"
},
"encryptedProperties": {
"Password": "$SYSTEM_USER_CLIENT_SECRET$"
},
"automaticOutboundCertificateRenew": false,
"transformationChanged": true,
"readTransformationChanged": false,
"writeTransformationChanged": false,
"fromImport": false,
"transformation": {
"user": {
"condition": "($.emails.length() > 0)",
"mappings": [
{
"sourceVariable": "entityIdTargetSystem",
"targetPath": "$.id"
},
{
"constant": [

"urn:ietf:params:scim:schemas:core:2.0:User",

"urn:ietf:params:scim:schemas:extension:enterprise:2.0:
User",

"urn:ietf:params:scim:schemas:extension:sap:2.0:User",

Incentive Management Admin Design Guide

424 PUBLIC Integration
 "urn:sap:cloud:scim:schemas:extension:custom:2.0:User"
],
"targetPath": "$.schemas"
},
{
"sourcePath": "$.userName",
"targetPath": "$.userName"
},
{
"constant": "userName",
"targetVariable":
"entityCorrelationAttributeName"
},
{
"sourcePath": "$.userName",
"targetVariable":
"entityCorrelationAttributeValue"
},
{
"sourcePath": "$.locale",
"optional": true,
"targetPath": "$.locale"
},
{
"sourcePath": "$.emails[*].value",
"preserveArrayWithSingleElement": true,
"targetPath": "$.emails[?(@.value)]"
},
{
"constant": "employee",
"targetPath": "$.userType",
"scope": "createEntity"
},
{
"sourcePath": "$.name.givenName",
"optional": true,
"targetPath": "$.name.givenName"
},
{
"sourcePath": "$.name.middleName",
"optional": true,
"targetPath": "$.name.middleName"
},
{
"sourcePath": "$.name.familyName",
"optional": true,
"targetPath": "$.name.familyName"
},
{
"sourcePath": "$.name.honorificPrefix",
"optional": true,
"targetPath": "$.name.honorificPrefix"
},
{
"sourcePath": "$.addresses",
"preserveArrayWithSingleElement": true,
"optional": true,
"targetPath": "$.addresses",
"functions": [
{
"function": "putIfAbsent",
"key": "type",

Incentive Management Admin Design Guide

Integration PUBLIC 425
 "defaultValue": "work"
},
{
"function": "putIfPresent",
"condition": "(@.type NIN ['work',
'home'])",
"key": "type",
"defaultValue": "work"
}
],
"defaultValue": []
},
{
"sourcePath": "$.phoneNumbers",
"preserveArrayWithSingleElement": true,
"optional": true,
"targetPath": "$.phoneNumbers"
},
{
"sourcePath": "$.displayName",
"optional": true,
"targetPath": "$.displayName"
},
{
"sourcePath": "$.timezone",
"optional": true,
"targetPath": "$.timezone"
},
{
"sourcePath": "$.active",
"optional": true,
"targetPath": "$.active",
"defaultValue": true
},
{
"constant": true,
"targetPath": "$
['urn:ietf:params:scim:schemas:extension:sap:2.0:User']
['sendMail']",
"scope": "createEntity"
},
{
"ignore": true,
"constant": "$.password",
"targetPath": "$.password",
"scope": "createEntity"
},
{
"sourcePath": "$.applicationId",
"optional": true,
"targetPath": "$
['urn:ietf:params:scim:schemas:extension:sap:2.0:User']
['applicationId']",
"scope": "createEntity"
},
{
"condition":
"$.incentiveManagementUserType == 'participant'",
"constant": [
{
"id": "$AUTHENTICATED_COMM-
SCAN_GROUP_ID$"
},

Incentive Management Admin Design Guide

426 PUBLIC Integration
 {
"id": "$APP_SCAN_GROUP_ID$"
},
{
"id": "$APP_SCAI_GROUP_ID$"
}
],
"targetVariable": "assignGroup"
},
{
"condition":
"($.incentiveManagementUserType == 'commadmin')
|| ($.incentiveManagementUserType == 'commadmin/
participant')",
"constant": [
{
"id": "$ADMINISTRATOR_COMM-
SCAN_GROUP_ID$"
},
{
"id": "$ADMINISTRATOR_COMM-
SCAI_GROUP_ID$"
},
{
"id": "$APP_SCAN_GROUP_ID$"
},
{
"id": "$APP_SCAI_GROUP_ID$"
}
],
"targetVariable": "assignGroup"
},
{
"condition":
"$.incentiveManagementUserType == 'portal_user'",
"constant": [
{
"id": "$APP_SCAN_GROUP_ID$"
},
{
"id": "$APP_SCAI_GROUP_ID$"
}
],
"targetVariable": "assignGroup"
},
{
"condition":
"($.incentiveManagementUserType != 'commadmin')
&& ($.incentiveManagementUserType != 'commadmin/
participant')",
"constant": [
{
"id": "$ADMINISTRATOR_COMM-
SCAN_GROUP_ID$"
},
{
"id": "$ADMINISTRATOR_COMM-
SCAI_GROUP_ID$"
}
],
"targetVariable": "unassignGroup"
},
{

Incentive Management Admin Design Guide

Integration PUBLIC 427
 "condition":
"($.incentiveManagementUserType != 'commadmin')
&& ($.incentiveManagementUserType != 'commadmin/
participant') && ($.incentiveManagementUserType !=
'participant')",
"constant": [
{
"id": "$ADMINISTRATOR_COMM-
SCAN_GROUP_ID$"
},
{
"id": "$ADMINISTRATOR_COMM-
SCAI_GROUP_ID$"
},
{
"id": "$AUTHENTICATED_COMM-
SCAN_GROUP_ID$"
}
],
"targetVariable": "unassignGroup"
},
{
"condition":
"($.incentiveManagementUserType != 'commadmin')
&& ($.incentiveManagementUserType != 'commadmin/
participant') && ($.incentiveManagementUserType !=
'participant') && ($.incentiveManagementUserType !=
'portal_user')",
"constant": [
{
"id": "$AUTHENTICATED_COMM-
SCAN_GROUP_ID$"
},
{
"id": "$APP_SCAN_GROUP_ID$"
},
{
"id": "$APP_SCAI_GROUP_ID$"
},
{
"id": "$ADMINISTRATOR_COMM-
SCAN_GROUP_ID$"
},
{
"id": "$ADMINISTRATOR_COMM-
SCAI_GROUP_ID$"
}
],
"targetVariable": "unassignGroup"
}
]
},
"group": {
"mappings": [
{
"sourceVariable": "entityIdTargetSystem",
"targetPath": "$.id"
},
{
"constant": [

"urn:ietf:params:scim:schemas:core:2.0:Group",

Incentive Management Admin Design Guide

428 PUBLIC Integration
 "urn:sap:cloud:scim:schemas:extension:custom:2.0:Group"
],
"targetPath": "$.schemas"
},
{
"sourcePath": "$.displayName",
"targetPath": "$.displayName"
},
{
"sourcePath": "$.members[*].value",
"preserveArrayWithSingleElement": true,
"optional": true,
"targetPath": "$.members[?(@.value)]",
"functions": [
{
"function": "resolveEntityIds",
"entityType": "user"
}
]
},
{
"sourcePath": "$.displayName",
"targetPath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['name']",
"scope": "createEntity",
"functions": [
{
"function": "replaceAllString",
"regex": "[\\s\\p{Punct}]",
"replacement": "_"
}
]
},
{
"sourcePath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['name']",
"optional": true,
"targetPath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['name']",
"scope": "createEntity"
},
{
"sourcePath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['description']",
"optional": true,
"targetPath": "$
['urn:sap:cloud:scim:schemas:extension:custom:2.0:Group
']['description']"
}
]
}
},
"gitFetchAllowed": false
}

2. Replace everything between $$ with the values related to your tenant:

• Replace $IAS_BASE_URL$ with your IAS url.

Incentive Management Admin Design Guide

Integration PUBLIC 429
 • Replace $SYSTEM_USER_CLIENT_ID$ with system client id from the step 2.
• Replace $SYSTEM_USER_CLIENT_SECRET$ with system client secret from the step
2.
• Replace $APP_SCAN_GROUP_ID$ with group id of the APP_SCAN group from step 3.
• Replace $APP_SCAI_GROUP_ID$ with group id of the APP_SCAI group from step 3.
• Replace $AUTHENTICATED_COMM-SCAN_GROUP_ID$ with group id of the AU-
THENTICATED_COMM-SCAN group from step 3.
• Replace $ADMINISTRATOR_COMM-SCAN_GROUP_ID$ with group id of the ADMIN-
ISTRATOR_COMM-SCAN group from step 3.
• Replace $ADMINISTRATOR_COMM-SCAI_GROUP_ID$ with group id of the ADMINIS-
TRATOR_COMM-SCAI group from step 3.

3. Click Create Target System and upload the JSON file.

4. Save the updates.

Testing User Sync

Perform the following steps to test user sync:

1. In Incentive Management Admin > Participants, create a participant user.

2. In Identity Provisioning > Source Systems, find the IncentiveManagement_SOURCE_PORTAL source
system, and choose Jobs > Resync Job > Run Now.
3. In Identity Provisioning > Provisioning Logs, verify if the job was successful.
4. In Identity Authentication > User Management, search for the user that you added as a Participant in
Incentive Management Admin. The user must be found and the Groups should be attached to this user.

Troubleshooting

If the Identity Provisioning job has failed, the Identity Provisioning > Provisioning Logs dashboard lists the
details.

These are some common errors that may occur during the user sync process and the steps to resolve them:

• "Oauth request failed with status: 401...": Check if the Source systems have the correct username and
password. The username and password should be populated with clientId and clientSecret from the step 1.
• "HTTP operation failed with statusCode: "400" and body message "JWT validation failed...": Check if
IAS OIDC application from step 1 is configured correctly (check if "aud" attribute in OIDC application is
configured) and if the Service Account is added in Incentive Management.
• "HTTP operation failed with statusCode: 403...": Check if the correct Role and Group is assigned to the
Service Account from step 1.
• "All target systems are marked as invalid due to the following reasons...HTTP operation failed... with
statusCode: 401": Check if the target system has the correct username and password. The username and
password should be populated with clientId and clientSecret from step 2.

Incentive Management Admin Design Guide

430 PUBLIC Integration
• "User is not synced in IAS, but the job is successful.": Check if the user has an email address configured
in Incentive Management. All users without an email address will be skipped.
• "The request to create an entity has failed with: 409 Conflict 'A user with the same primary email
already exists!' ": By default, Identity Authentication does not accept two users with the same email
address. This configuration can be changed in Identity Authentication, but you can also avoid creating
users with same email address in Incentive Management Admin.

Related Information

Configuring User Sync When Username in Incentive Management is Different than Login Name in Identity
Authentication [page 432]

28.2.1.5 Configuration to Replicate Administration Users

Configuration in SAP SuccessFactors Incentive Management

Create a user in the Incentive Management Admin with role Administrator and set a password. Identity
Provisioning will call the SAP SuccessFactors Incentive Management SCIM API with this user.

 Note

The recommendation is to create a separate user for this integration instead of reusing an existing one. A
separate user would mean better separation of concerns and better traceability in case of issues.

Configuration in Identity Provisioning

Source System for SAP SuccessFactors Incentive Management

The SAP Note 2999357 contains a sample configuration for the source system that one can upload
to Identity Provisioning. Please download the attachment Bottom-Up-Source-SAP-Commissions-Admin-
V3.json. The provided configuration is a recommendation and is is optional to use.

The type of the source system to be created is SCIM System. See related Identity Provisioning documentation
here: SCIM System and Add a System.

On the Source System Creation page, use the option Define from File and upload the file Bottom-Up-Source-
SAP-Commissions-Admin-V3.json here. The source system is now populated with the values from this file.
Later, perform the following changes:

Tab Details

Provide a system name.

Tab Transformations

Incentive Management Admin Design Guide

Integration PUBLIC 431
In case you don’t require groups and user to group assignments to be transferred, you can discard them using
the transformation expression “ignore” as explained in Transformation Expressions.

Tab Properties

Set these properties:

Property Name Value Comment

ips.trace.failed.entity.content true Both values true and false are possible.

Value true gives you better analysis op-
tions in case of errors. A potential setup
is, for e.g., to use true in the Test envi-
ronment and false in Production.

Password < Password assigned in Incentive Man- Enter the password you assigned the
agement Admin > user.

URL https://<SAP SuccessFactors Incentive Replace <SAP SuccessFactors

Management Tenant URL>/ TrueComp- Incentive Management Tenant URL>
SaaS/services/v3/scim with the URL of the tenant.

User < Incentive Management Admin user id Enter the user name created before.
of the user created above >

Target System for SAP Identity Authentication

Please reuse the target system defined above. Add the source system for SAP SuccessFactors Incentive
Management in “Source Systems” in the Details tab.

28.2.1.6 Initial Load of Users / Periodic Transfer of Users

To initially load all relevant SAP SuccessFactors Incentive Managements user records into Identity
Authentication, go to the tab Jobs in the Identity Provisioning system and run a read job as explained in Start
and Stop Provisioning Jobs. Check the job logs as explained in Manage Provisioning Job Logs.

You can schedule a periodic job for the ongoing automatic transfer of user changes from SAP SuccessFactors
Incentive Managements to Identity Authentication. One can receive E-Mail alerts in case of errors.

You need to execute these activities for each source system.

28.2.1.7 Configuring User Sync When Username in Incentive

Management is Different than Login Name in
Identity Authentication

If Identity Authentication is already populated with users and those users have a different Login Name
in Identity Authentication than the Username in Incentive Management, additional changes in the Identity
Authentication SAML application and Identity Provisioning transformations are required.

Incentive Management Admin Design Guide

432 PUBLIC Integration
Procedure

This sections illustrates the steps to perform when the Username in Incentive Management is different than the
Login Name in Identity Authentication. For example, if the Username in Incentive Management is same as the
User Email (and not the Login Name) in Identity Authentication, perform the following steps:

1. Set up the Incentive Management user login mapping:

1. Navigate to the Identity Authentication Admin page and open the Applications section.
2. Search for Sales Performance Home application.
3. Open the Subject Name Identifier section.
4. Set the Primary Attribute value to Email.
2. If you are using Identity Provisioning to sync users from Incentive Management to Identity Authentication,
then set up Identity Provisioning transformations to read email attribute as 'unique':
1. Navigate to Identity Provisioning.
2. Open the Identity Authentication Target System defined for the Incentive Management application
3. In the Properties tab, choose Edit, and set the value for the ias.user.unique.attribute property to
emails[0].value (default value is "userName").
4. In the Transformations tab, select Switch to JSON Editor and choose Edit to set the following
mappings.
• Search for the userName mapping and add the createEntity scope as shown in the sample code
below:
Default Mapping:

 Sample Code

{
"sourcePath": "$.userName",
"targetPath": "$.userName"
}

New Mapping:

 Sample Code

{
"sourcePath": "$.userName",
"targetPath": "$.userName",
"scope": "createEntity"
}

• Search for the entity correlation mapping and set the email value instead of userName as shown in
the sample code below:
Default Mapping:

 Sample Code

{
"constant": "userName",
"targetVariable": "entityCorrelationAttributeName"
},
{
"sourcePath": "$.userName",
"targetVariable": "entityCorrelationAttributeValue"

Incentive Management Admin Design Guide

Integration PUBLIC 433
 }

New Mapping:

 Sample Code

{
"constant": "emails.value",
"targetVariable": "entityCorrelationAttributeName"
},
{
"sourcePath": "$.emails[0].value",
"targetVariable": "entityCorrelationAttributeValue"
}

• Search for the email mapping and add the createEntity scope as shown in the sample code below:
Default Mapping:

 Sample Code

{
"sourcePath": "$.emails[*].value",
"targetPath": "$.emails[?(@.value)]",
"preserveArrayWithSingleElement": true
}

New Mapping:

 Sample Code

{
"sourcePath": "$.emails[*].value",
"targetPath": "$.emails[?(@.value)]",
"preserveArrayWithSingleElement": true,
"scope": "createEntity"
}

3. Save your changes.

Related Information

Setting Up User Synchronization from SAP Incentive Management to Identity Authentication Using Identity
Authentication SCIM v2 [page 416]

28.2.1.8 Additional Information

This topic provides additional notes about Bottom-Up User Synchronization.

Incentive Management Admin Design Guide

434 PUBLIC Integration
• In release 2012 Group Assignments for Portal users are NOT transferred from SAP SuccessFactors
Incentive Management to Identity Authentication. Group Assignments for Incentive Management Admin
users are correctly transferred.
• Incentive Management group ids are case-sensitive. For Example: COMM_ADM_1 and comm_adm_1 can
exist in parallel in SAP SuccessFactors Incentive Management. Identity Authentication does not support
this and raises an error when two such groups are transferred from SAP SuccessFactors Incentive
Management.
• In SAP SuccessFactors Incentive Management several users with one and the same E-Mail address can
exist. In Identity Authentication this is configurable. See Configure Allowed Logon Identifiers. If Identity
Authentication uses unique E-Mail addresses, Identity Authentication raises an error in case two users with
the same E-Mail are transferred from SAP SuccessFactors Incentive Management.
• This integration relies on SCIM APIs, V3. The OpenAPI specifications for these APIs are attached to the
SAP Note 2999357 and is published on the SAP API business hub.

28.2.2 Top-Down User Synchronization

In the top-down user synchronization approach, users are created in the Identity Authentication application
and pushed to SAP SuccessFactors Incentive Management, using the Identity Provisioning application. In this
process you can create users who belong to the following user groups:

• Participants
• Approvers
• Managers
• Administrators

28.2.2.1 Creating a Participant User Using the Top-Down

Process

Participant records and the user records in SAP SuccessFactors Incentive Managementare separate records.
They are linked by the user id (field name “User Name” in the Participant UI).

The Identity Authentication > SAP SuccessFactors Incentive Management integration only creates Incentive
Management Portal user records in SAP SuccessFactors Incentive Management, not full-blown Participant
records.

Participant records need to be created separately. They can be created in the UI, via the REST API or via file
upload.

It doesn’t matter if the Participant record is created first or if the user record is created first.

For example, when SAP SuccessFactors Incentive ManagementParticipant is created first:

1. A participant with participant id “Jane_Doe” is created. The user name is set to “jane_doe”.
2. The system automatically creates the Incentive Management Portal user with user id “jane_doe”.
3. A user “jane_doe” is created in Identity Authentication.

Incentive Management Admin Design Guide

Integration PUBLIC 435
4. The Identity Authentication user is replicated from Identity Authentication to SAP SuccessFactors
Incentive Management. In SAP SuccessFactors Incentive Management the existing Incentive Management
Portal User “jane_doe” is updated with the data sent by Identity Authentication.

For example, when Identity Authentication User is created first:

1. A user “jane_doe” is created in Identity Authentication.

2. The Identity Authentication user is replicated to SAP SuccessFactors Incentive Management. In SAP
SuccessFactors Incentive Management a new Incentive Management Portal User “jane_doe” is created
with the data sent by Identity Authentication.
3. A participant with participant id “Jane_Doe” is created. The user name is set to “jane_doe”.
4. The system updates the existing user “jane_doe” with the user relevant information from the Participant
record.

Procedure

1. Log in to Identity Authentication.

2. In the User & Authorization workspace choose User Management.
3. Click the Add User button.
4. Enter the following values:
• First Name
• Last Name
• E-Mail
• Login Name
• User Type
5. Set the Account Activation to Send activation email.
6. Click the Save button.
7. Select the user that you created and click the User Group icon.
8. Click Assign Group.
9. Add the user to the COMM app and select the Participant-COMM group for the user and click Save.

If No Scheduled Read Job Exists in Identity Provisioning to Periodically

Replicate Users

The next part of the user creation process is conducted in the Identity Provisioning application. These steps
are only relevant if there is no scheduled read job in Identity Provisioning that periodically replicates users from
Identity Authentication to SAP SuccessFactors Incentive Managements.

1. Log in to Identity Provisioning.

2. Go to Source System for Identity Authentication.
3. Go to the Jobs tab.
4. Run Resync Job in order to sync the user.

Log into SAP SuccessFactors Incentive Management to verify that the participant user is successfully created.

Incentive Management Admin Design Guide

436 PUBLIC Integration
Result:The Incentive Management Portal Participant User is now successfully added to SAP SuccessFactors
Incentive Management.

28.2.2.2 Creating an Administrator Using the Top-Down

Process

Perform the following steps to create an Administrator using the Top-Down Process.

1. Log into Identity Authentication.

2. In the User & Authorization workspace choose User Management.
3. Click the Add User button.
4. Enter the following values:
• First Name
• Last Name
• E-Mail
• Login Name
• User Type
5. Set the Account Activation to Send activation email.
6. Click the Save button.
7. Select the user that you created and click the User Group icon.
8. Click Assign Group.
9. Add the user to the COMM app and select the Administrator-COMM group for the user and click Save.

The next part of the user creation process is conducted in the Identity Provisioning application.

1. Log in to Identity Provisioning.

2. In the Subaccounts workspace locate your environment.
3. Go to Services > Identity Provisioning.
4. Click Go to Service.
5. Go to Source System > SAP SuccessFactors Incentive Management > Jobs.
6. Run Resync Job in order to sync the user.
7. Log into SAP SuccessFactors Incentive Management to verify that the administrator user is successfully
created.

Result: The administrator user is now successfully added to SAP SuccessFactors Incentive Management.

28.2.2.3 Creating a Manager User Group Using the Top-Down

Process

Perform the following steps to create a Manager User Group using the Top-Down Process.

1. Log in to Identity Authentication.

2. In the User & Authorization workspace choose User Management.
3. Click the Add User button.

Incentive Management Admin Design Guide

Integration PUBLIC 437
4. Enter the following values:
• First Name
• Last Name
• E-Mail
• Login Name
• User Type
5. Set the Account Activation to Send activation email.
6. Click the Save button.
7. Select the user that you created and click the User Group icon.
8. Click Assign Group.
9. Add the user to the COMM app and select the Manager-COMM group for the user and click Save.

The next part of the user creation process is conducted in the Identity Provisioning application.

1. Log in to Identity Provisioning.

2. In the Subaccounts workspace locate your environment.
3. Go to Services >Identity Provisioning.
4. Click Go to Service.
5. Go to Source System > SAP SuccessFactors Incentive ManagementJobs.
6. Run Resync Job in order to sync the user.
7. Log into SAP SuccessFactors Incentive Management to verify that the user from the manager user is
successfully created.

Result: The user from the manager user group is now successfully added to SAP SuccessFactors Incentive
Management.

28.2.2.4 Creating an Approver User Group Using the Top-

Down Process

Perform the following steps to create an Approver User Group using the Top-Down Process.

1. Log in to Identity Authentication.

2. In the User & Authorization workspace choose User Management.
3. Click the Add User button.
4. Enter the following values:
• First Name
• Last Name
• E-Mail
• Login Name
• User Type
5. Set the Account Activation to Send activation email.
6. Click the Save button.
7. Select the user that you created and click the User Group icon.
8. Click Assign Group.
9. Add the user to the COMM app and select the Approver-COMM group for the user and click Save.

Incentive Management Admin Design Guide

438 PUBLIC Integration
The next part of the user creation process is conducted in the Identity Provisioning application.

1. Log into Identity Provisioning.

2. In the Subaccounts workspace, locate your environment.
3. Go to Services > Identity Provisioning.
4. Click Go to Service.
5. Go to Source System > SAP SuccessFactors Incentive Management > Jobs.
6. Run Resync Job in order to sync the user.
7. Log into SAP SuccessFactors Incentive Management to verify that the user from the approver user is
successfully created.

Result: The user from the approver user group is now successfully added to SAP SuccessFactors Incentive
Management.

28.2.3 About Identity Provisioning and Identity

Authentication SSO Integration for SAP
SuccessFactors Incentive Management

SAP SuccessFactors Incentive Management requires users to authenticate using SAP Cloud Identity Services
for SSO. SSO configuration is available by default. If a different SAP IDP is used, it is set up during
the tenant provisioning process. When a customer is using corporate IdP to authenticate users, Identity
Authentication Service is configured to use corporate IdP for user authentication. The purpose of this setup
is to enable corporate IdP for SSO with Identity Authentication Service to log in to SAP SuccessFactors
Incentive Management. Corporate IdP is configured for users with a corporate e-mail domain using conditional
authentication rules, and all other users are authenticated using Identity Authentication Service.

 Note

The SAML authentication protocol is used to enable secure communication between SAP Identity
Authentication and SAP SuccessFactors Incentive Management. OpenID Connect based authentication
is not supported by SAP SuccessFactors Incentive Management currently.

Single Sign-On (SSO) Options

Single Sign-On (SSO) enables single sign-on and single identity synchronization across the sales performance
management solutions in the SAP SuccessFactors portfolio.

Single Sign-On uses SAP Cloud Identity Services to support the use of either direct single sign-on or federated
single sign-on.

Sales performance management solutions Single Sign-On is powered by SAP Cloud Identity Services, which
contains:

• Identity Authentication Service - An IdP that supports user and group management and allows
configurations for single sign-on. This IdP can also act as a service-provider, if needed.
• Identity Provisioning Service - Provisions users from Identity Authentication to the applications or service
providers, and vice versa from applications to Identity Authentication. This solution provides a unified
customer experience across sales performance management applications and provides a single point of
entry for user onboarding and access control.

Incentive Management Admin Design Guide

Integration PUBLIC 439
See the illustrations below for details on the architecture for Direct Single Sign-on (Identity Authentication as
the IdP) and Federated Single Sign-on (Corporate IdP).

Option 1 - Direct Single Sign-On (Identity Authentication as the IdP)

Identity Authentication service acts as the identity provider and user store. When customer tenants are
provisioned, Direct Single Sign-On is already configured and activated for customers.

Option 2 - Federated Single Sign-On (Corporate IdP)

Customer's preferred corporate identity provider is used for federated single sign-on. The following image
depicts the technical architecture of sales performance management Single Sign-On using federated single
sign-on. Security Assertion Markup Language (SAML) is used to connect Identity Authentication service
with the corporate identity provider. The articles in this topic primarily focus on setting up Federated Single
Sign-On.

Incentive Management Admin Design Guide

440 PUBLIC Integration
28.2.4 Renewing SAML Certificates

SAML is primarily used for single sign-on (SSO) authentication and access control. SAML certificates are
generated when a tenant is created. Two distinct certificates are generated for signing and encryption
purposes. These certificates remain valid for a duration of 1 year. To ensure uninterrupted service, new
certificates are generated 1 month before the expiration of the existing ones. The older certificates continue to
be used until their expiration date. During this 1 month, we allow the IAS administrator ample time to update
SAML IAS applications with the new certificates.

SAML certificates are used in:

• IAS SAML application (both signature and encryption certificates are used)
• IAS OIDC application (only signature certificates are used)

Procedure

1. Navigate to the specified URL: TENANT_URL/iamsvc/saml/metadata. Replace "TENANT_URL" with the

actual URL of your tenant. You are presented with information about one or two active public certificates
for signing and one or two active public certificates for encryption.
2. Copy the latest signing and latest encryption certificate in order to register them in Identity Authentication.
These are required to update IAS SAML and OIDC applications.

 Note

If there are two certificates in active status, the second one is the most recent.

Incentive Management Admin Design Guide

Integration PUBLIC 441
3. Go to the respective Identity Authentication instance.
4. Go to Applications and find the SAML application of the required tenant. (The Name of the application is in
the following format: Sales Performance Home ${TENANT_SUBDOMAIN}).
5. Choose SAML Configuration.

 Note

You cannot upload the metadata file because it will read only one certificate.

6. In the Signing Certificate configuration section, choose Add. You need to manually add the signing
certificate copied in step 2.

 Note

You can define only 2 signing certificates in the SAML IAS application. If there is already one signing
certificate defined in the Identity Authentication, you just need to add the newest certificate from step
2. If there are already two signing certificates defined in Identity Authentication, you need to delete the
expired one (oldest one) and add the newest signing certificate from step 2. If you delete the signing
certificate that is still active, it will interrupt the service and users will not be able to log in to SAP
SuccessFactors Incentive Management.

Incentive Management Admin Design Guide

442 PUBLIC Integration
 Adding the signing certificate:

7. In Insert as Text, add the signing certificate copied in step 2.

8. In the Encryption Certificate configuration section, choose Add. You need to manually add the encryption
certificate copied in step 2.

Incentive Management Admin Design Guide

Integration PUBLIC 443
  Note

You can define only one encryption certificate in the SAML IAS application. In order to add a new one,
you need to delete the current one, and then add the newest encryption certificate copied in step 2.

Adding the encryption certificate:

9. In Insert as Text, add the encryption certificate copied in step 2.

10. Choose Save.

Incentive Management Admin Design Guide

444 PUBLIC Integration
11. Go to Applications and find the OIDC application of the required tenant. (Name of the application is in the
following format: COMM_${TENANT_SUBDOMAIN}_OIDC_${tenantUrl}.
12. Choose Client Authentication and scroll down to the Certificates section.
13. Use the Delete icon to delete the previous certificate.

14. Choose Add and in Insert as Text, add the signing certificate copied in step 2.

The updates are automatically saved.

Incentive Management Admin Design Guide

Integration PUBLIC 445
28.3 Integration with SAP Business Technology Platform
(BTP)

SAP BTP is a cloud-based development platform that offers robust and powerful capabilities to connect
and integrate Incentive Management to various applications and data sources with both SAP and non-SAP
products. These prebuilt SAP BTP services can be leveraged to meet the sales performance management
(SPM) requirements for Data Management and Analytics, which allows for faster and scalable preprocessing,
optimization, and analysis of data. This helps to improve overall business efficiency and drives data-driven
decisions for better business outcomes.

SAP Datasphere is a comprehensive SAP BTP data service that provides a unified experience for data
federation, virtualization, integration, and warehousing needs. It can seamlessly connect with the SAP
Incentive Management on SAP HANA database system using an out-of-the-box cloud connector and act
as a central location to bring data from other data sources and landscapes and facilitate integrations with
Incentive Management. Additionally, SAP Datasphere also provides a platform to design and build analytical
models, which makes the consumption of analytical data in SAP Analytics Cloud, or by third party reporting
and analytical tools, easier.

SAP Automation Pilot, also an SAP BTP service, can be utilized to automate the complex manual processes
and increase operational efficiency. By using the SAP SuccessFactors Incentive Management provided
command catalog within SAP Automation Pilot, the service events can be orchestrated to move large volumes
of data to Incentive Management, execute pipeline jobs, and build various custom scenarios. The ability to
configure SAP Alert Notifications Services with SAP Automation Pilot makes it easier to create and manage
alerts and receive real-time notifications on each of the process tasks. It also provides capabilities to schedule
and monitor the execution of the jobs from a centralized module.

When SAP BTP is used as an agile innovation platform, customers can benefit with reduced total cost of
ownership, faster time-to-value. and future-prove their investment and architecture.

BTP Datasphere Integration with SAP SuccessFactors Incentive Management

You must first open a SAP support case as per the instructions provided in the related knowledge base
article .

Once the setup is complete, the SAP Datasphere tenant contains a prebuilt connection to the Incentive
Management database. Using this connection, data can be read from both TCMP and EXT schemas. Data can
be written only to select permitted tables of the TCMP and all tables within the EXT schema.

Refer to the following training material for more information on BTP Datasphere:

• Introduction to Datasphere from OpenSAP

• Explore SAP Datasphere Learning Journey
• Introduction to SAP Datasphere
• Get Started with SAP Datasphere
• Get to Know the SAP Datasphere Interface
• Data Modeling for Business with SAP Datasphere

Incentive Management Admin Design Guide

446 PUBLIC Integration
• Create Hierarchies with SAP Datasphere
• Configure Spaces (Secure Virtual Work Environment) and Setup Tenant Connections

SAP Automation Pilot and SAP Alert Notification Service Integration with
SAP SuccessFactors Incentive Management

SAP Automation Pilot and SAP Alert Notification Service are BTP services used for the processing,
orchestration, and automation of technical and business operations. See the SAP Automation Pilot
documentation and the SAP Alert Notification documentation for more details.

28.3.1 Default Catalogs for Automation Pilot and Alert

Notification Service

SAP SuccessFactors Incentive Management delivers accelerator catalogs for SAP Automation Pilot and SAP
Alert Notification Service that can be used by customers and partners for out-of-the-box integrations.

See the respective help topics for more information on the default catalogs:

• Importing the Default Core Catalog for SAP SuccessFactors Incentive Management [page 451]
• Importing the Default Tenant Specific Catalog for SAP SuccessFactors Incentive Management [page 457]
• Importing the Default Catalog for SAP Alert Notification Service [page 448]

Automation Pilot Catalogs

The default catalogs for Automation Pilot are the following:

• SuccessFactors Incentive Management Core Catalog: The core catalog is based on non-tenant-specific
data. It makes use of internal sequences (for periods, calendars, etc.) and all commands require
mandatory inputs for connectivity parameters. See Importing the Default Core Catalog for SAP
SuccessFactors Incentive Management [page 451] for more details.
• SuccessFactors Incentive Management Tenant Catalog: The tenant catalog needs to be instantiated
for individual tenants. It requires a one-time configuration of a catalog input for connectivity parameters
for Incentive Management and Data Sphere. It also requires synchronization of master data for Periods,
Calendars, Period Types, and Processing Units. The delivered commands in the tenant catalog derive the
connection parameters from the inputs. Also, the required parameters are based on user-friendly fields
but not internal sequences. See Importing the Default Tenant Specific Catalog for SAP SuccessFactors
Incentive Management [page 457] for more details.

The default Automation Pilot catalogs provide commands for the following functionalities:

• Validation and Transfer Pipelines

• Compensate and Pay Pipelines
• Approval Pipelines
• Datasphere Task Chains
• Smart Command to guess the latest non-processed batch name (for stage sales transactions).

Incentive Management Admin Design Guide

Integration PUBLIC 447
• Smart Command to guess the periods which need to be processed by a single imported batch.

Partners are encouraged to use the default Automation Pilot commands to create new commands as an
orchestration process based on the Incentive Management catalog commands. The implementation team may
clone any of the default commands and perform modifications as needed.

Alert Notification Service Catalog

The default catalog for Alert Notification Service enables email notifications after the following events:

• Pipeline finished (Validate and Transfer, Compensate and Pay, Approve)

• DataSphere Task Chain finished

Both events are sent in case of successful execution or error.

The Incentive Management Core catalog contains an input called ANSConnection, which provides an
integration point between Automation Pilot and Alert Notification Service.

See Importing the Default Catalog for SAP Alert Notification Service [page 448] for more details.

Related Information

Integration with SAP Business Technology Platform (BTP) [page 446]

28.3.2 Importing the Default Catalog for SAP Alert

Notification Service

The compensation administrators and datasphere administrators receive email notifications about the status
of execution pipelines or task chains through SAP Alert Notification Service. To receive notifications regarding
the status of the commands in SAP Automation Pilot, you must configure the Alert Notification Service.

The following table lists all the objects that are delivered with the Alert Notification Service template.

Subscription Description

subscription_dsTaskChainFinished Subscription for datasphere Administrator

subscription_pipelineFinished Subscription for Incentive Management Compensation Ad-

ministrator

Action Description

emailNotification_dataSphere Email notification for datasphere task chain

emailNotification_compAdmin Email notification for Incentive Management Compensation

Administrator

Condition Description

eventType_DSTaskChainFinished EventType matching DSTaskChainFinished

eventType_PipelineFinished EventType matching PipelineFinished

Incentive Management Admin Design Guide

448 PUBLIC Integration
Procedure

To import the SAP Alert Notification Service command catalog, perform the following procedure:

1. Download [page 499] the SuccessFactors Incentive Management Alert Notification

Service catalog file and save it locally.
2. Copy the content of the Alert Notification file.
3. Navigate to SAP Alert Notification Service tenant and navigate to the Export or Import tab.
4. Paste the catalog's content and choose Import.

After importing the catalog, Subscriptions, Actions, and Conditions as shown in the screens below are
created.

Incentive Management Admin Design Guide

Integration PUBLIC 449
5. Configure your email addresses in the Actions section. Every action allows only one email address -
individual email or a Distribution List. To add a list of emails, create a separate action for each individual
email and match it to the corresponding subscription email. Select each action individually, select Edit and
modify the email address.

Incentive Management Admin Design Guide

450 PUBLIC Integration
 After you save, the action is in Not Enabled status. An initial enablement email is sent to the configured
email address. The recipient must click on the link in the email to enable the Email Action.

Related Information

Default Catalogs for Automation Pilot and Alert Notification Service [page 447]

28.3.3 Importing the Default Core Catalog for SAP

SuccessFactors Incentive Management

The default core catalog for SAP SuccessFactors Incentive Management is Success Factors Incentive
Management Core.

The following inputs and commands are provided in the catalog.

Command Description

checkAndWaitForDataSphereTaskChain Check status and wait until Data Sphere task chain finishes.

checkAndWaitForPipelineExecution Check status and wait until pipeline finishes.

runDataSphereTaskChain Run Data Sphere task chain.

runFullApproveCalcDataPipeline Run a full approve pipeline and wait for the result.

runFullCompAndPayPipeline Run a full compensate and pay pipeline and wait for the
result.

Incentive Management Admin Design Guide

Integration PUBLIC 451
runValidateAndTransferTxnOrderCreditsPipeline Run a validate and transfer pipeline (transactions, orders,
credits) and wait for the result.

sendNotificationAndErrorState Send notification about pipeline status.

sendNotificationAndErrorStateDataSphere Send notification about Data Sphere status.

smartBatchNameDetection Detect batchname for pipeline run.

smartPeriodDetection Detect periods for pipeline run.

triggerDataSphereTaskChain Trigger Data Sphere task chain.

triggerFullApproveCalcDataPipeline Trigger full pipeline run for Approval.

triggerFullCompAndPayPipeline Trigger full pipeline run for Compensate and Pay.

triggerValidateAndTransferTxnOrdersCredits Trigger full pipeline run for Validate and Transfer.

Input Description

ANSConnection Connectivity parameters required for Alert Notification Serv-

ice.

serviceAccountCredentials Required for internal connection to Automation Pilot.

See Configuring a Service Account for Automation Pilot [page 453] and Configuring Connectivity to SAP Alert
Notification Service [page 455] for information on configuring the required inputs.

Procedure

To import the core command catalog into SAP Automation Pilot, perform the following procedure:

1. Download [page 499] the Success Factors Incentive Management Core command catalog file and
save it locally.
2. Copy the content of the downloaded Success Factors Incentive Management Core catalog file.
3. Go to your SAP Automation Pilot tenant and navigate to My Catalogs.
4. Choose Import.

Incentive Management Admin Design Guide

452 PUBLIC Integration
5. Paste the catalog's content with “Extended Catalog as JSON” placeholder in the text and choose Import.

After importing the catalog into SAP Automation Pilot, you'll see a new catalog tile – SuccessFactors Incentive
Management Core. From there, you can navigate to all commands and inputs which are part of the catalog.

Related Information

Download Core Catalog Commands [page 499]

Download Core Catalog Inputs [page 503]

28.3.3.1 Configuring a Service Account for Automation Pilot

For SAP Automation Pilot, the Success Factors Incentive Management Core command catalog
requires an additional service account.

Incentive Management Admin Design Guide

Integration PUBLIC 453
Procedure

1. To create the additional service account, go to SAP Automation Pilot and choose the Service Accounts
tab.
2. Choose Create.
3. In the Create Service Account dialog, enter the following details:
• Username: Enter a username that doesn't already exist within the Automation Pilot instance.
• Description: Provide any desired description for the account.
• Permissions: Select both Read and Write permissions.
• Authentication Type: Choose Basic as the authentication type.

4. Choose Create. A new service account (username) is created and a new password is generated.
5. To populate the username and password in the serviceAccountCredentials input, configure the input
serviceAccountCredentials with the username and password generated in step 4. (See the following
screenshot for example. The username is T000168R3-IncentiveManagement).

Incentive Management Admin Design Guide

454 PUBLIC Integration
Related Information

Importing the Default Core Catalog for SAP SuccessFactors Incentive Management [page 451]

28.3.3.2 Configuring Connectivity to SAP Alert Notification

Service

You must create a service key for the SAP Alert Notification Service and configure the ANSConnection in SAP
Automation Pilot. This connection enables Automation Pilot to trigger email notifications as required.

Procedure

1. To configure connectivity to SAP Alert Notification Service, log in to SAP Alert Notification Service and
choose Create Service Key.

2. In the Create Service Key dialog, enter the following details:

• Name: Enter a unique name for the service key. For example, you can use BasicANSKey.
• Configuration Parameters: Create a JSON configuration for the service key. Enter the Name and
Configuration Parameters as displayed in the following example:

3. Choose Create. A newly created service key is displayed as shown in the following example:

Incentive Management Admin Design Guide

Integration PUBLIC 455
4. Log in to SAP Automation Pilot and navigate to Success Factors Incentive Management Core Catalog >
Inputs > ANSConnection.
The Success Factors Incentive Management Core catalog contains an input called
ANSConnection. This input is used to establish a connection between SAP Automation Pilot and SAP
Alert Notification Service.
5. Enter the values obtained from step 3 into the respective keys:
• client_id: [Value from previous step]
• client_secret: [Value from previous step]
• url: [Value from previous step]

Related Information

Importing the Default Core Catalog for SAP SuccessFactors Incentive Management [page 451]

Incentive Management Admin Design Guide

456 PUBLIC Integration
28.3.4 Importing the Default Tenant Specific Catalog for SAP
SuccessFactors Incentive Management

The tenant specific catalog must be imported and configured separately for each Incentive Management
tenant. The tenant specific catalog includes two inputs (connections) to the Incentive Management system and
the BTP Datasphere.

The following inputs and commands are provided in the catalog.

Command Description

execDataSphereTaskChain Execute SAP Datasphere task chain.

execFullApproveCalcDataPipeline Execute a full approve pipeline and wait for the result.

execFullCompAndPayPipeline Execute a full compensate and pay pipeline and wait for the
result.

execValidateAndTransferTxnOrderCreditsPipeline Execute a validate and transfer pipeline (transactions, or-

ders, credits) and wait for the result.

smartBatchNameDetection Detect batchname for pipeline run.

smartPeriodDetection Detect periods for pipeline run.

smartPeriodDetection Get all calendars from Incentive Management.

syncAllProcessingUnits Get all processing units from Incentive Management.

syncAllPeriodTypes Get all period types from Incentive Management.

syncAllPeriods Get all periods from Incentive Management.

syncAllMasterData Get all calendars, period types, processing units and periods
from Incentive Management.

Input Description

SFIMConnection Connection parameters for Incentive Management system

DataSphereConnection Connection parameters for Data Sphere

Procedure

To import the core command catalog into SAP Automation Pilot, perform the following procedure:

1. Download [page 499] the Success Factors Incentive Management Tenant command catalog file
and save it locally.
2. Copy the content of the downloaded SuccessFactors Incentive Management Tenant catalog file.
• For each of the tenants that will be used, clone the downloaded copy of the JSON file, and replace all
occurrences of the keyword SFIMTENANT with SFIM<TENANTID>, for example, SFIMG123.
• Update the default Name: Change from the default "Success Factors Incentive Management Tenant"
to a descriptive and meaningful name for this individual customer, such as "UAT G123" or "Production
G456".

Incentive Management Admin Design Guide

Integration PUBLIC 457
 • Update the default Description: Change from the default "Accelerator Tenant Catalog for Success
Factors Incentive Management" to an individual description, for example, "Catalog for G123 used for
UAT testing" or "Catalog for Production tenant G456".
3. Go to your SAP Automation Pilot tenant and navigate to My Catalogs.
4. Choose Import.

5. Paste the catalog's content with “Extended Catalog as JSON” placeholder in the text and choose Import.

After importing the catalog into SAP Automation Pilot, you'll see a new catalog tile as illustrated below. From
there, you can navigate to all commands and inputs which are part of the catalog.

Related Information

Download Tenant Catalog Commands [page 503]

Download Tenant Catalog Inputs [page 505]

Incentive Management Admin Design Guide

458 PUBLIC Integration
28.3.4.1 Configuring Connectivity to SFTP

Connectivity to SFTP must to configured.

Procedure

1. Provide connectivity parameters for SFTP in the input SFTPConnection. It has 4 keys: host, port,
privateKey, and username.

2. Copy the host, port, and username details from Express Data Loader > File Transfer Settings for the
required tenant and populate them in the input.
3. For the privateKey parameter, a private/public pair needs to be created. First, upload the public key to
Express Data Loader > File Transfer Settings. After that, convert the private key into the openSSH format
(if not already in this format), then base64 encode it, and populate it in the input.

Incentive Management Admin Design Guide

Integration PUBLIC 459
28.3.4.2 Configuring Connectivity to SAP SuccessFactors
Incentive Management Tenant

You need to configure the connectivity parameters for the Incentive Management tenant
at input SFIMConnection. It consists of 5 keys: clientId, clientSecret, domain (default value
is .app.commissions.cloud.sap), tenantId (four-letter identifier, such as G123), and tokenUrl.

See Service Account Authentication for instructions on how to obtain the required parameters.

To configure the required SFIM connection parameters, go to Success Factors Incentive Management
<Tenant> catalog > inputs > SFIMConnection and provide the required details:

28.3.4.3 Configuring Connectivity to SAP Datasphere

See Create OAuth2.0 Clients to Authenticate Against SAP Datasphere and Authorized Consent Settings for an
overview.

Incentive Management Admin Design Guide

460 PUBLIC Integration
Creating an OAuth User in SAP Datasphere

1. To create an OAuth user in SAP Datasphere, go to SAP Datasphere.

2. Navigate to System > Administration > App Integration.
3. Choose Add New OAuth Client.
4. In the New OAuth Client screen, provide the following details:
• Enter a distinct Name (e.g., automation_pilot).
• Select the Purpose as "Interactive Usage".
• In Redirect URI, enter http://localhost:8080.

5. Choose Add. The OAuth Client Information screen is displayed.

• Choose Show Secret to reveal the secret, then copy it.
• Copy the OAuthClientID.

Incentive Management Admin Design Guide

Integration PUBLIC 461
 • Copy the Authorization URL and Token URL.

You will require the copied information to complete the configuration steps described inObtaining SAP
Datasphere Refresh Token below.

Configuring Consent Settings

1. To configure Consent Settings, go to SAP Datasphere.

2. Navigate to User Profile > Authorized Consent Settings.
3. In the Authorized Consent Settings page, choose Authorize.

Incentive Management Admin Design Guide

462 PUBLIC Integration
Obtaining SAP Datasphere Refresh Token

The Refresh Token will have to be obtained by the SAP Datasphere administrator once every month. See
Accessing SAP Datasphere via the Command Line for more details on the process.

1. In the SAP Datasphere administrator's system, in a CMD or shell console, install datasphere CLI with:

 Sample Code

npm install -g @sap/datasphere-cli

2. Validate that the datasphere CLI is installed with the following command. It should return the latest
datasphere CLI version.

 Sample Code

datasphere --version

3. Set the host of datasphere. <url> is the URL of datasphere. It should be the main url without any URI.

 Sample Code

datasphere config host set <url>

Incentive Management Admin Design Guide

Integration PUBLIC 463
4. Run the datasphere login, provide the ClientID, Client Secret, Authorization URL, and Token URL. These
four parameters are obtained from step 5 in the section Create an OAuth User in DataSphere described
above.

 Sample Code

datasphere login
Please enter your client ID: … <Client ID>
Please enter your client secret: … ****
Please enter your authorization URL: … <Authorization URL>
Please enter your token URL: … <Token URL>

A browser popup is displayed and the datasphere administrator must provide their username and
password to continue.
5. Run:

 Sample Code

datasphere config secrets show

6. Find the section with refresh_token and make a note of this value:

Configuring SAP Datasphere Connection Input

To configure the SAP Datasphere input connection, go to SAP Automation Pilot > <Tenant> catalog > Inputs
> Datasphere Connection and provide the following details:

• dsClientID - clientID for the OAuth user as specified

• dsClientSecret - client secret for the OAuth user as specified
• dsRefreshToken - the refresh token as specified (See Obtaining SAP Datasphere Refresh Token described
above.)
• dsTenantURL - the url of BTP Data Sphere. It should not include any URI in the URL
• dsTokenURL - the token url as specified

Incentive Management Admin Design Guide

464 PUBLIC Integration
Related Information

Importing the Default Tenant Specific Catalog for SAP SuccessFactors Incentive Management [page 457]

28.3.4.4 Synchronizing Master Data

The tenant catalog uses the following inputs as list of values for the master data used in SAP SuccessFactors
Incentive Management. The keys of each input for each tenant is unique. For example, every tenant will have a
different list of calendars or a different list of periods.

• ProcessingUnits
• Calendars
• PeriodTypes
• Periods

The list of values for all the four types is synchronized with the SAP SuccessFactors Incentive Management
application and populated in Automation Pilot. After the initial import of the tenant catalog, the administrator
must manually trigger each command individually in the following order:

1. syncAllProcessingUnits
2. syncAllCalendars
3. syncAllPeriodTypes
4. syncAllPeriods

After the initial synchronization, the administrator can schedule automatic synchronization (for example on a
weekly basis) - syncAllMasterData.

Incentive Management Admin Design Guide

Integration PUBLIC 465
syncAllProcessingUnits

This command synchronizes all processing units within Incentive Management with the automation pilot
catalog input processingUnits.

It contains the following executors:

• getProcessingUnitsList: This executor reads all the data from the Incentive Management and produces a
JSON output which contains key/value pairs of type internal sequence/user friendly text.
• transformProcessingUnitNames: Internal transformation step of the json input from the previous step.
• transformation: This command uses Automation Pilot API and populates the input processingUnits with
values that are filtered in the previous step.

syncAllCalendars

This command synchronizes all calendars in Incentive Management with input calendars.

Incentive Management Admin Design Guide

466 PUBLIC Integration
This contains the following executors:

• getCalendarsList: This executor reads all the data from the Incentive Management and produces a JSON
output which contains key/value pairs of type internal sequence/user friendly text.
• transformCalendarNames: Internal transformation step of the json input from the previous step.
• transformation: This command uses Automation Pilot API and populates the input calendars with values
that are filtered in the previous step.

syncAllPeriodTypes

This command synchronizes all period types in Incentive Management with input periodTypes.

It uses the following executors:

• getPeriodTypesList : This executor reads all the data from the Incentive Management and produces a
JSON output which contains key/value pairs of type internal sequence/user friendly text.
• transformPeriodTypeNames: Internal transformation step of the json input from the previous step.
• transformation: This command uses Automation Pilot API and populates the input periodTypes with
values that are filtered in the previous step.
• Additional values: Keys from SFIMConnection input for connection with Incentive Management.

syncAllPeriods

This command synchronizes all periods in Incentive Management with input periods. It is more complex than
previous sync commands as it uses values. When the command is triggered, the administrator must provide
the following inputs: calendar, periodType, start Year (default 2023) and end Year (default 2025). Considering
the start year and the end year, the number of the calculated periods (for the particular calendar/period type)
should be less than 100.

Incentive Management Admin Design Guide

Integration PUBLIC 467
The following list of executors are in use:

• getPeriodsList: This executor reads all the data from the Incentive Management and produces a JSON
output which contains key/value pairs of type internal sequence/user friendly text.
• transformPeriodNames: Internal transformation step of the json input from the previous step.
• transformation: This command uses Automation Pilot API and populates the input periods with values
that are filtered in the previous step.
• calendarValue: This additional value is used for getting value for sequence for calendar that is chosen from
dropdown in the input of this command.
• periodTypeValue: This additional value is used for getting value for sequence for periodType that is chosen
from dropdown in the input of this command.

syncAllMasterData

This command is used as a combination of the four commands and as such is convenient for scheduling and
having these inputs updated on a daily basis.

Input is the same as for syncAllPeriods command: Calendar, PeriodType, Start Year, End Year.

Incentive Management Admin Design Guide

468 PUBLIC Integration
28.3.4.5 Scheduling Synchronization for Master Data

Master data synchronization can be scheduled periodically.

Procedure

1. Go to SAP Automation Pilot > Scheduled Executions, and choose Schedule.

2. Under Configuration, select the tenant catalog syncAllMasterData for Command. Provide the required
details and choose Next Step.

3. Provide the input Parameters as specified below and choose Next Step.
• calendar: For example, Main_Monthly_Calendar
• periodType: For example, month
• endYear and startYear string: Only the periods with the specific period type between startYear and
endYear will be synchronized with Automation Pilot. Choose these inputs carefully - only 100 periods
can be synchronized with Incentive Management. If startYear and endYear are too far apart, the
command fails.

Incentive Management Admin Design Guide

Integration PUBLIC 469
4. Specify the Schedule to indicate the time pattern for the execution of the command. In the example below,
the command is scheduled to run once a week - on every Sunday at 5:00 am.

5. Choose Next Step to finalize and save the details.

28.3.5 Automation Pilot Core Catalog

The commands from the core catalog require a deeper understanding of the Incentive Management system.
The inputs for master data, such as calendars and periods, are not user-friendly texts but rather internal
technical sequences. Additionally, you must always explicitly provide the connectivity parameters for the
Incentive Management system

All core catalog commands use the following pattern:

1. trigger<Pipeline>: Invokes the API to trigger a pipeline (Validate&Transfer, Comp&Pay or Approval).

2. checkAndWaitForPipelineExecution: This command waits for pipeline execution. The default behaviour of
this command is to poll for the result every minute for 4 hours (240 min). These parameters can be
adjusted by the implementation partner.

Incentive Management Admin Design Guide

470 PUBLIC Integration
3. sendNotificationAndErrorState: This command sends an email notification through Alert Notification
Service with a short description of the execution, status, and overall runtime. If an error occurs (indicating
a pipeline failure), the command will halt and prompt the Administrator to decide whether to disregard the
failure and proceed with executing the commands or to designate the overall command status as FAILED.
Customers and Partners have the option to customize the behavior of this command.

Related Information

Run Validate & Transfer Pipeline [page 473]

Run Compensate & Pay Pipeline [page 474]
Run Approval Pipeline [page 476]
Run Express Data Loader (XDL) Data Extract [page 471]
Run Reset from Validate Pipeline [page 479]
Run Reset from Classify Pipeline [page 481]

28.3.5.1 Run Express Data Loader (XDL) Data Extract

A command called runXDLDataExtract is available in the core catalog. This command is used to run XDL data
extract stage from the pipeline through triggering API.

There is a corresponding command in tenant catalog called execXDLDataExtract. It internally invokes invokes
runXDLDataExtract command from core catalog.

Incentive Management Admin Design Guide

Integration PUBLIC 471
Input Parameters

• clientId, clientSecret, domain, tokenUrl, tenantId: Connectivity parameters for Incentive Management.
• fileType: Outbound file type that will be run in XDL.
• ANSClientID, ANSClientSecret, ANSUrl: Connectivity parameters for Alert Notification Service.
• dataFilter: This parameter is used as an input parameter for the EXT procedure which is used for extracting
data. (This is an optional parameter and it can also be left blank if EXT procedure expects no input
parameters. If EXT procedure has two or more input parameters, then there must be comma delimited
within the dataFilter input.)

Output Parameters

• Status: Status of the execution

Incentive Management Admin Design Guide

472 PUBLIC Integration
Internal Executors

• triggerJob: This executor invokes post API to trigger XDL job.

• checkStatus: This executor checks status of the XDL job.
• sendNotification: This executor uses the sendNotification command which is used for sending notification
through Alert Notification Service. It also gets inputs from the user if the pipeline has failed.

28.3.5.2 Run Validate & Transfer Pipeline

A command called runValidateAndTransferTxnOrderCreditsPipeline is available in the core catalog. This

command is used to run Validate and Transfer for sales transactions, and Orders and Credits.

It supports two modes - All and New.

There is a corresponding command in tenant catalog called

execValidateAndTransferTxnOrderCreditsPipeline. It internally invokes the
runValidateAndTransferTxnOrderCreditsPipeline command from the core catalog but it defaults the
connection parameters from the default input.

Incentive Management Admin Design Guide

Integration PUBLIC 473
Input Parameters

• calendarSeq: Sequence number for a calendar.

• batchname: Batch Name required for Validate and Transfer.
• processingUnitSeq: Sequence number for a processing unit.
• Mode: This parameter allows two possible values - All or New.
• clientId, clientSecret, tokenUrl, tenantId: Connectivity parameters for Incentive Management.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed.

Internal Executors

• triggerVNTPipeline: This command invokes the API to trigger Validate And Transfer pipeline.
• checkAndWaitForPipelineExecution: This executor uses the command checkAndWaitForPipelineExecution
command which takes pipelineRunSeq from the previous step, gets status and message of the pipeline and
pass them to next step.
• sendNotificationAndErrorState: This executor uses the sendNotificationAndErrorState command which is
used for sending email notifications through Alert Notification Service.

28.3.5.3 Run Compensate & Pay Pipeline

A command called runFullCompAndPayPipeline can be used to run compensate and pay pipeline in Full mode.

There is a corresponding command in the tenant catalog called execFullCompAndPayPipeline. It internally

invokes the runFullCompAndPayPipeline command from the core catalog but it defaults the connection
parameters from the default input.

Incentive Management Admin Design Guide

474 PUBLIC Integration
Input Parameters

• calendarSeq: Sequence number for a calendar.

• periodSeq: Sequence number for a period.
• processingUnitSeq: Sequence number for a processing unit.
• runDataExtracts: Triggers Data Extract phase at the end of Comp and Pay pipeline. It requires a valid input
for dataExtractsFileType parameter.
• dataExtractsFileType: A valid XFL file type.
• runStage: Run stage supports two possible values - Summarize and Comp and Pay.
• clientId, clientSecret, tokenUrl, tenantId: Connectivity parameters for Incentive Management.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed.

Incentive Management Admin Design Guide

Integration PUBLIC 475
Internal Executors

• triggerFullCompAndPayPipeline: Invokes the API to trigger Full Comp And Pay pipeline.
• checkAndWaitForPipelineExecution: This executor uses the checkAndWaitForPipelineExecution command
which takes pipelineRunSeq from the previous step, gets status and message of the pipeline and pass
them to next step.
• sendNotificationAndErrorState: This executor uses the sendNotificationAndErrorState command which is
used for sending email notifications through Alert Notification Service.

28.3.5.4 Run Approval Pipeline

A command called runFullApproveCalcDataPipeline is available in the core catalog. This command is used to
run Approval Pipeline in Full mode.

There is a corresponding command in the tenant catalog called execFullApproveCalcDataPipeline. It internally

invokes the runFullApproveCalcDataPipeline command from the core catalog but it defaults the connection
parameters from the default input.

Input Parameters

• calendarSeq: Sequence number for a calendar.

• periodSeq: Sequence number for a period.
• processingUnitSeq: Sequence number for a processing unit.
• clientId, clientSecret, tokenUrl, tenantId: Connectivity parameters for Incentive Management.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed

Incentive Management Admin Design Guide

476 PUBLIC Integration
Internal Executors

• triggerFullApprovePipeline: Invokes the API to trigger Approval Pipeline.

• checkAndWaitForPipelineExecution: This executor uses the checkAndWaitForPipelineExecution command
which takes pipelineRunSeq from the previous step, gets status and message of the pipeline and pass
them to next step.
• sendNotificationAndErrorState: This executor uses the sendNotificationAndErrorState command which
is used for sending notification through Alert Notification Service and getting user’s choice if pipeline is
failed.

28.3.5.5 Run Monitor SFTP Directory

A command called runMonitorSFTPDirectory is available in the core catalog.

This command is used to monitor if a file exists in the given directory in an sftp server defined by the
connection parameters Host/Port/Username/PrivateKey. If at least one file exists and it matches the
provided prefix and suffix, then the matching files will be moved to a directory targetDirectory.

The parameter fileNameAfterMove provides possible renaming options for the file rename:

• If the value is same then the file will be moved with the same name as is in the inbound directory
• If a different value is provided, only one of the files will be moved and will be named with the file name
fileNameAfterMove

After the file is moved, a new alert will be triggered to the Alert Notification Service with event type as provided
in the input parameter eventType. Then the project team will process the alert by triggering the corresponding
workflow which processes the files. The workflow maybe another Automation Pilot command or any other ANS
action.

There is a corresponding command in tenant catalog called monitorSFTPConnection.

Incentive Management Admin Design Guide

Integration PUBLIC 477
Input Parameters

• EventType: Event type that needs to be matched in order to send the notification to Alert Notification
Service.
• Host: Host used for SFTP connection. This can be found in the Express Data Loader (XDL) user interface.
• Port: Port used for SFTP connection. This can be found in the Express Data Loader (XDL) user interfaceI.
• PrivateKey: For privateKey parameter, private/public pair needs to be created. First, you must upload the
public key to the Express Data Loader (XDL) > File Transfer Settings tab. After that, you must convert the
private key into openSSH format (if not already in this format) and then base64 encode it
• Username: Username used for SFTP connection. This can be found in the Express Data Loader (XDL) user
interface.
• InboundDirectory: The field designated for inputting the name of the directory from which the file is
intended to be relocated.
• TargetDirectory: The field designated for inputting the name of the directory to which the file is intended to
be transferred.
• fileNameAfterMove: The field designated for the specification of the new filename after transfer.

Incentive Management Admin Design Guide

478 PUBLIC Integration
• FileNamePrefix: The field designated for entering the prefix name of the file intended for relocation.
• FileNameSufix: The field designated for entering the sufix name of the file intended for relocation.
• ANSClientID, ANSClientSecret, ANSUrl: Connectivity parameters for Alert Notification Service.

Output Parameters

• Debug Message: Full message from SFTP connection (only for debugging purposes).
• Message: A message providing an overall description for the executed pipeline.

Internal Executors

28.3.5.6 Run Reset from Validate Pipeline

A command called runResetFromValidatePipeline is available in the core catalog.

Incentive Management Admin Design Guide

Integration PUBLIC 479
Input Parameters

• calendarSeq: Sequence number for a calendar.

• periodSeq: Sequence number for a period.
• clientId, clientSecret, domain, tokenUrl, tenantId: Connectivity parameters for Incentive Management
(SFIM Connection input).
• batchname: Batch Name required for Validate and Transfer.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed

Incentive Management Admin Design Guide

480 PUBLIC Integration
Internal Executors

• triggerResetFromValidatePipeline: This command invokes the API to trigger.

• checkAndWaitForPipelineExecution: This executor uses the checkAndWaitForPipelineExecution command
which takes pipelineRunSeq from the previous step, gets the status and message of the pipeline and
passes it on to the next step.
• sendNotificationAndErrorState: This executor uses the sendNotificationAndErrorState command which is
used for sending email notifications through SAP Alert Notification Service.

28.3.5.7 Run Reset from Classify Pipeline

A command called runResetFromClassifyPipeline is available in the core catalog.

Incentive Management Admin Design Guide

Integration PUBLIC 481
Input Parameters

• calendarSeq: Sequence number for a calendar.

• periodSeq: Sequence number for a period.
• clientId, clientSecret, domain, tokenUrl, tenantId: Connectivity parameters for Incentive Management
(SFIM Connection input)
• mode: This parameter supports only the value All.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

Incentive Management Admin Design Guide

482 PUBLIC Integration
• Status: Status of the pipeline - Success or Failed.

Internal Executors

• triggerResetFromClassifyPipeline: This command invokes the API to trigger.

• checkAndWaitForPipelineExecution: This executor uses the command checkAndWaitForPipelineExecution
command which takes pipelineRunSeq from the previous step, gets status and message of the pipeline and
pass them to next step.
• sendNotificationAndErrorState: This executor uses sendNotificationAndErrorState command which is
used for sending email notifications through Alert Notification Service.

28.3.6 Automation Pilot Tenant Specific Catalog

The SuccessFactors Incentive Management Tenant catalog serves as a template for individual SAP
SuccessFactors Incentive Management tenants. If a customer has multiple tenants, they must create a
corresponding number of tenant catalogs using the process outlined in Importing the Default Tenant Specific
Catalog for SAP SuccessFactors Incentive Management [page 457].

Each individual tenant catalog must be configured with the respective tenant connections for SAP
SuccessFactors Incentive Management (See Configuring Connectivity to SAP SuccessFactors Incentive
Management Tenant [page 460]) and SAP Datasphere (See Configuring Connectivity to SAP Datasphere [page
460]).

The next steps use the master data which is already synchronized (as described in Synchronizing Master Data
[page 465]) and eventually scheduling regular synchronizations (See Scheduling Synchronization for Master
Data [page 469]).

These commands are intended for use by compensation administrators and end-users who may not be familiar
with the internal sequences employed by SAP SuccessFactors Incentive Management.

Related Information

Execute Express Data Loader (XDL) Data Extract [page 484]

Execute Validate & Transfer Pipeline [page 487]
Execute Compensate & Pay Pipeline [page 488]

Incentive Management Admin Design Guide

Integration PUBLIC 483
Execute Approval Pipeline [page 490]
Execute Reset from Classify Pipeline [page 491]
Execute Reset from Validate Pipeline [page 492]

28.3.6.1 Execute Express Data Loader (XDL) Data Extract

The Command execXDLDataExtract uses the command runXDLDataExtract from the core catalog as it
passes the connection parameters from SFIMConnection.

Input Parameters

• fileType: Outbound file type that will be run in XDL.

• dataFilter: This parameter is used as an input parameter for the EXT procedure which is used for extracting
data. This is an optional parameter and it can also be left blank if the EXT procedure expects no input
parameters. If the EXT procedure has two or more input parameters, then there must be comma delimited
within the dataFilter input.

Output Parameters

• status: Status of the job - Success or Failed

Incentive Management Admin Design Guide

484 PUBLIC Integration
Internal Executors

• runXDLDataExtract - Invokes the runXDLDataExtract command from the core catalog.

28.3.6.2 Monitor SFTP Directory

The command monitorSFTPDirectory is used to monitor if a file exists in a given directory. If at least one
file exists and it matches the provided prefix and suffix, then the matching files will be moved to a directory
targetDirectory.

The parameter fileNameAfterMove provides possible renaming options for the file rename:

• If the value is same, then the file will be moved with the same name as is in the inbound directory
• If a different value is provided, only one of the files will be moved and will be named with the file name
fileNameAfterMove

After the file is moved, a new alert will be triggered to the Alert Notification Service with event type as provided
in the input parametereventType. Then the project team will process the alert by triggering the corresponding
workflow which processes the files. The workflow maybe another Automation Pilot command or any other ANS
action.

Internally it uses the command runMonitorSFTPDirectory from the core catalog as it passes the connection
parameters from the SFTP Connection. See Configuring Connectivity to SFTP [page 459] for more details.

Incentive Management Admin Design Guide

Integration PUBLIC 485
Input Parameters

• EventType: Event type that needs to be matched in order to send the notification to Alert Notification
Service.
• InboundDirectory: The field designated for inputting the name of the directory from which the file is
intended to be relocated.
• TargetDirectory: The field designated for inputting the name of the directory to which the file is intended to
be transferred.
• fileNameAfterMove: The field designated for the specification of the new filename after transfer.
• FileNamePrefix: The field designated for entering the prefix name of the file intended for relocation.
• FileNameSufix: The field designated for entering the sufix name of the file intended for relocation.

Output Parameters

A message providing an overall description for the executed pipeline.

Incentive Management Admin Design Guide

486 PUBLIC Integration
Internal Executors

• runSFTPMonitor - Invokes the runSFTPMonitor command from the core catalog.

28.3.6.3 Execute Validate & Transfer Pipeline

The command execValidateAndTransferTxnOrderCreditsPipeline runs a Validate and Transfer pipeline in

Incentive Management. Internally it uses the command runValidateAndTransferTxnOrderCreditsPipeline
from the core catalog as it passes the connection parameters from SFIMConnection and translates the user-
friendly texts from the inputs into sequences.

Incentive Management Admin Design Guide

Integration PUBLIC 487
Input Parameters

• batchname: The batch name for validate and transfer.

• calendar: The name of the calendar.
• mode: All or New.
• processingUnit: The processing unit for which to run Validate and Transfer (optional parameter).

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed.

Internal Executors

• runValidateAndTransfer: Invokes runValidateAndTransferTxnOrderCreditsPipeline command from core

catalog.

28.3.6.4 Execute Compensate & Pay Pipeline

The command execFullCompAndPayPipeline runs the Compensate and Pay pipeline in Incentive
Management. Internally it uses the command runFullCompAndPayPipeline from the core catalog as it passes
the connection parameters from SFIMConnection and translates the user-friendly texts from the inputs into
sequences.

Incentive Management Admin Design Guide

488 PUBLIC Integration
Input Parameters

• calendar: The name of the calendar.

• period: The user-friendly name of the period.
• dataExtractsFileType: File type for data extracts for XDL.
• runDataExtracts: Possible values true/false (default false) indicates if it will run an XDL data extract at the
end of the pipeline.
• runStage: Possible values Comp And Pay (full pipeline) or Summarize (pipeline will stop after allocate
stage).
• mode: All or New.
• processingUnit: The processing unit for which to run Validate and Transfer (optional parameter).

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed.

Internal Executors

• unFullCompAndPayPipeline: Invokes the runFullCompAndPayPipeline command from core catalog.

Incentive Management Admin Design Guide

Integration PUBLIC 489
28.3.6.5 Execute Approval Pipeline

The command execFullApproveCalcDataPipeline runs the Approve pipeline in Incentive Management.

Internally it uses the command runFullApproveCalcDataPipeline from the core catalog as it passes the
connection parameters from SFIMConnection and translates the user-friendly texts from the inputs into
sequences.

Input Parameters

• calendar: The name of the calendar.

• period: The user-friendly name of the period.
• processingUnit: The processing unit for which to run Validate and Transfer (optional parameter).

Incentive Management Admin Design Guide

490 PUBLIC Integration
Internal Executors

• runFullApproveCalcDataPipeline: Invokes run runFullApproveCalcDataPipeline from core catalog.

28.3.6.6 Execute Reset from Classify Pipeline

The command execResetFromClassifyPipeline is used for executing Reset From Classify stage in Pipeline.

Internally it uses the command runResetFromClassify from the core catalog as it passes the connection
parameters from SFIMConnection and translates the user-friendly texts from the inputs into sequences.

Input Parameters

calendar: the name of the calendar

period: the user-friendly name of the period

mode: This parameter supports only the value All.

Incentive Management Admin Design Guide

Integration PUBLIC 491
Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed.

Internal Executors

runReset

• FromClassify: Invokes the runResetFromClassify command from core catalog.

28.3.6.7 Execute Reset from Validate Pipeline

The command execResetFromValidatePipeline is used for executing Reset From Validate stage in Pipeline.

Internally it uses the command runResetFromValidate from the core catalog as it passes the connection
parameters from SFIMConnection and translates the user-friendly texts from the inputs into sequences.

Incentive Management Admin Design Guide

492 PUBLIC Integration
Input Parameters

• calendar: the name of the calendar.

• period: the user-friendly name of the period.
• batchname: the batch name for validate and transfer.

Output Parameters

• Message: A message providing an overall description for the executed pipeline.

• Status: Status of the pipeline - Success or Failed

Internal Executors

• runResetFromValidate: Invokes the runResetFromValidate command from core catalog.

Incentive Management Admin Design Guide

Integration PUBLIC 493
28.3.7 Smart Detection Commands

Both the CORE and Tenant catalogs contain additional commands and functionalities that the Automation Pilot
developers can leverage to build more complex scenarios:

• smartBatchNameDetection
• smartPeriodDetection

smartBatchNameDetection

Different customers may use SAP Datasphere to load data into stage tables - CS_STAGESALESTRANSACTION
or CS_STAGESALESORDER. After the load is done, the next step of the flow is to run the Validate and
Transfer Pipeline (using execValidateAndTransferTxnOrderCreditsPipeline from the tenant catalog or the
runValidateAndTransferTxnOrderCreditsPipeline command from the CORE catalog). This command requires
a few mandatory parameters, which usually will be static besides batchname.

The common practice for the developers who load the data in stage tables is to use automated generation of
batch names. These batch names usually follow the following pattern:

<prefix><datetime><suffix>

Example:

G123_TXST_PRD_20220511_231638.txt

In this example case

Incentive Management Admin Design Guide

494 PUBLIC Integration
G123_TXST_PRD is the prefix

20220511_231638 is the datetime

.txt is the suffix

The purpose of the command is to detect the latest batch name which is part of CS_STAGESALESORDER
or CS_STAGESALESTRANSACTION that matches the particular pattern. If either of these tables contain a
batchname which does not match the pattern, then this batchname will be ignored.

Input Parameters

• prefix: The batch name has to start with this prefix.

• regularExpression: Regular expression for the datetime portion of the batchname.
• suffix: The ending of the batchname.

Output Parameters

batchname: A batch name which matches the pattern defined by the input parameters and contains a non-
processed transaction or order and has the latest value.

Example: If you have the following two batchnames which match the criteria:

G123_TXST_PRD_20220511_231638.txt and G123_TXST_PRD_20220512_231638.txt

then the output of the command will be G123_TXST_PRD_20220512_231638.txt

since it corresponds to the latest datetime.

smartPeriodDetection

This command is used for the scenario in which a developer needs to combine a run for Validate and
Transfer Pipeline (using execValidateAndTransferTxnOrderCreditsPipeline from the tenant catalog or the
runValidateAndTransferTxnOrderCreditsPipeline command from the CORE catalog). A particular batch may

Incentive Management Admin Design Guide

Integration PUBLIC 495
contain transactions with Compensation Dates which belong to different periods. The smartPeriodDetection
command will identify an array of periods which are part of this batch. The identification will be based on the
inputs for PeriodType and Calendar.

This command will be used as a connection between a single execution of the Validate and Transfer
pipeline and the following executions of the Compensation and Pay pipeline based on the periods within the
batchname.

Input Parameters

• Batchname: The batch name for stage transaction data.

• PeriodType: Period Type for which the company runs its compensation - possible values : monthly,
quarterly, weekly, biweekly etc.
• Calendar: Calendar used by the customer.

Output Parameters

• Periods: A list of period names

28.3.8 Commands for Running Data Sphere Task Chains

Both the CORE catalog and the TENANT-specific catalog provide commands for executing data sphere
task chains. While the command in the CORE catalog requires explicit connectivity parameters to
Datasphere, the TENANT-specific catalog utilizes the connectivity parameters already configured in the
DataSphereConnection, simplifying the command execution process

Incentive Management Admin Design Guide

496 PUBLIC Integration
CORE Catalog - runDataSphereTaskChain

The command runDataSphereTaskChain runs three internal executors:

1. triggerDSTaskChain: This executor triggers the execution of the task chain. Internally, it uses the
DataSphere command-line client. See Manage Tasks and Task Chains via the Command Line for more
details.
2. checkAndWaitForDSTaskChain: This command waits for Task Chain execution. The default behavior of this
command is to poll for the result every minute for 250 minutes. These parameters can be adjusted by the
implementation partner.
3. sendNotificationAndErrorState: This command sends an email notification through the Alert Notification
Service with a short description of the execution, status, and overall runtime. If an error occurs (indicating
a DataSphere Task Chain failure), the command will halt and prompt the Administrator to decide whether
to disregard the failure and proceed with executing the commands or to designate the overall command
status as FAILED. Customers and Partners have the option to customize the behavior of this command.

Input Keys

The process of obtaining the initial five parameters is outlined in Configuring Connectivity to SAP Datasphere
[page 460].

• dsClientID: clientID for OAuth service user to Datasphere.

• dsClientSecret: clientID for Oauth service user to Datasphere.
• dsTenantURL: Tenant URL for Datasphere.
• dsTokenURL: Token URL for OAuth for Datasphere.
• dsRefreshToken: A valid refresh token for the service user for Datasphere.
• dsSpace: A valid space in which the task chain resides.
• dsTaskChain: The name of the task chain to trigger.

Incentive Management Admin Design Guide

Integration PUBLIC 497
Output Keys

• debug: A debug message from command triggerDSTaskChain.

• message: A message providing an overall description for the executed task chain.
• status: Status of the task chain - Success or Failed.

TENANT Catalog - execDataSphereTaskChain

The command execDataSphereTaskChain in the TENANT catalog uses the command

runDataSphereTaskChain from the CORE catalog. It uses the connectivity parameters - dsClientID,
dsClientSecret, dsRefreshToken, dsTenantURL, dsTokenURL from the input DataSphereConnection in the
same TENANT catalog.

Input Keys

• dsSpace: A valid space in which the task chain resides.

• dsTaskChain: The name of the task chain to trigger.

Output Keys

• debug: A debug message from command triggerDSTaskChain.

• message: A message providing an overall description for the executed task chain.
• status: Status of the task chain - Success or Failed.

Incentive Management Admin Design Guide

498 PUBLIC Integration
28.3.9 SAP Automation Pilot Integration: Downloads

The following default catalogs are available for download:

• Download SuccessFactors Incentive Management Alert Notification Service catalog

• Download Success Factors Incentive Management Core catalog
• Download Success Factors Incentive Management Tenant catalog

The following commands and inputs are available for download:

• Download Core Catalog Commands [page 499]

• Download Core Catalog Inputs [page 503]
• Download Tenant Catalog Commands [page 503]
• Download Tenant Catalog Inputs [page 505]

Related Information

Default Catalogs for Automation Pilot and Alert Notification Service [page 447]
Automation Pilot Core Catalog [page 470]
Automation Pilot Tenant Specific Catalog [page 483]

28.3.9.1 Download Core Catalog Commands

Click here to download the following Core Catalog Commands:

Incentive Manage-
ment Release Ver- Command File
COMMAND NAME sion Version FLAGS (*use latest if deprecated)

checkPipelineStatusAndSendNotifi- 2411 v1 RELEASED

cation.json

runModelRunPipeline.json 2411 v1 RELEASED

runPositionsApproveCalcDataPipe- 2411 v1 RELEASED

line.json

runPositionsCompAndPayPipe- 2411 v1 RELEASED

line.json

triggerModelRunPipeline.json 2411 v1 RELEASED

triggerPositionsApproveCalcDataPi- 2411 v1 RELEASED

peline.json

triggerPositionsCompAndPayPipe- 2411 v1 RELEASED

line.json

Incentive Management Admin Design Guide

Integration PUBLIC 499
 Incentive Manage-
ment Release Ver- Command File
COMMAND NAME sion Version FLAGS (*use latest if deprecated)

runMonitorSFTPDirectory.json 2411 v3 RELEASED

triggerValidateAndTransferTxnOrder- 2407 v4 RELEASED

sCredits

triggerValidateAndTransferPlanRela- 2407 v1 RELEASED

tedData

triggerValidateAndTransferOrganiza- 2407 v1 RELEASED

tionData

triggerValidateAndTransferClassifi- 2407 v1 RELEASED

cationData

triggerFullCompAndPayPipeline 2407 v3 RELEASED

triggerANSEvent 2407 v2 RELEASED

sendNotificationAndErrorState 2407 v3 RELEASED

runXDLDataExtract 2407 v4 RELEASED

runValidateAndTransferTxnOrderCre- 2407 v4 RELEASED

ditsPipeline

runValidateAndTransferPlanRelated- 2407 v1 RELEASED

DataPipeline

runValidateAndTransferOrganization- 2407 v1 RELEASED

DataPipeline

runValidateAndTransferClassifica- 2407 v1 RELEASED

tionDataPipeline

runResetFromValidatePipeline 2407 v3 RELEASED

runResetFromClassifyPipeline 2407 v2 RELEASED

runMonitorSFTPDirectory 2407 v2 DEPRECATED

runFullCompAndPayPipeline 2407 v3 RELEASED

runFullApproveCalcDataPipeline 2407 v3 RELEASED

runEXTStoredProcedure 2407 v3 RELEASED

runDataSphereTaskChain 2407 v5 RELEASED

runDataSphereTaskChain 2405 v4 RELEASED, DEPRECATED

checkAndWaitForDataSphereTask- 2405 v4 RELEASED

Chain

triggerValidateAndTransferTxnOrder- 2405 v3 RELEASED, DEPRECATED

sCredits

triggerResetFromValidate 2405 v2 RELEASED

runValidateAndTransferTxnOrderCre- 2405 v3 RELEASED, DEPRECATED

ditsPipeline

runResetFromValidatePipeline 2405 v2 RELEASED, DEPRECATED

Incentive Management Admin Design Guide

500 PUBLIC Integration
 Incentive Manage-
ment Release Ver- Command File
COMMAND NAME sion Version FLAGS (*use latest if deprecated)

checkAndWaitForDataSphereTask- 2405 v3 RELEASED, DEPRECATED

Chain

runDataSphereTaskChain 2405 v3 RELEASED, DEPRECATED

runXDLDataExtract 2405 v3 RELEASED, DEPRECATED

triggerXDLJob 2405 v3 RELEASED

checkAndWaitForDataSphereTask- 2405 v2 RELEASED, DEPRECATED

Chain

runDataSphereTaskChain 2405 v2 RELEASED, DEPRECATED

triggerXDLJob 2405 v2 RELEASED, DEPRECATED

runFullApproveCalcDataPipeline 2405 v2 RELEASED, DEPRECATED

runFullCompAndPayPipeline 2405 v2 RELEASED, DEPRECATED

runValidateAndTransferTxnOrderCre- 2405 v2 RELEASED, DEPRECATED

ditsPipeline

runXDLDataExtract 2405 v2 RELEASED, DEPRECATED

sendNotificationAndErrorState 2405 v2 RELEASED, DEPRECATED

smartBatchNameDetection 2405 v2 RELEASED

smartPeriodDetection 2405 v2 RELEASED

triggerDataSphereTaskChain 2405 v2 RELEASED

triggerEXTStoredProcedure 2405 v2 RELEASED

triggerFullApproveCalcDataPipeline 2405 v2 RELEASED

triggerFullCompAndPayPipeline 2405 v2 RELEASED, DEPRECATED

triggerValidateAndTransferTxnOrder- 2405 v2 RELEASED, DEPRECATED

sCredits

checkAndWaitForPipelineExecution 2405 v2 RELEASED

checkEXTStoredProcedureStatus 2405 v2 RELEASED

checkStatusOfXDLJob 2405 v2 RELEASED

runEXTStoredProcedure 2405 v2 RELEASED, DEPRECATED

checkEXTStoredProcedureStatus 2405 v1 RELEASED, DEPRECATED

checkStatusOfXDLJob 2405 v1 RELEASED, DEPRECATED

runEXTStoredProcedure 2405 v1 RELEASED, DEPRECATED

runXDLDataExtract 2405 v1 RELEASED, DEPRECATED

sendNotificationAndErrorStateEXT- 2405 v1 RELEASED, DEPRECATED

StoredProcedure

sendNotificationAndErrorStateXDL- 2405 v1 RELEASED, DEPRECATED

DataExtract

Incentive Management Admin Design Guide

Integration PUBLIC 501
 Incentive Manage-
ment Release Ver- Command File
COMMAND NAME sion Version FLAGS (*use latest if deprecated)

testSFTPConnectivity 2405 v1 RELEASED

triggerEXTStoredProcedure 2405 v1 RELEASED, DEPRECATED

runMonitorSFTPDirectory 2405 v1 RELEASED, DEPRECATED

triggerANSEvent 2405 v1 RELEASED, DEPRECATED

runResetFromClassifyPipeline 2405 v1 RELEASED, DEPRECATED

runResetFromValidatePipeline 2405 v1 RELEASED, DEPRECATED

triggerResetFromClassify 2405 v1 RELEASED

triggerResetFromValidate 2405 v1 RELEASED, DEPRECATED

checkAndWaitForDataSphereTask- 2402 v1 RELEASED, DEPRECATED

Chain

checkAndWaitForPipelineExecution 2402 v1 RELEASED, DEPRECATED

runDataSphereTaskChain 2402 v1 RELEASED, DEPRECATED

runFullApproveCalcDataPipeline 2402 v1 RELEASED, DEPRECATED

runFullCompAndPayPipeline 2402 v1 RELEASED, DEPRECATED

runValidateAndTransferTxnOrderCre- 2402 v1 RELEASED, DEPRECATED

ditsPipeline

sendNotificationAndErrorState 2402 v1 RELEASED, DEPRECATED

sendNotificationAndErrorStateData- 2402 v1 RELEASED, DEPRECATED

Sphere

smartBatchNameDetection 2402 v1 RELEASED, DEPRECATED

smartPeriodDetection 2402 v1 RELEASED, DEPRECATED

triggerDataSphereTaskChain 2402 v1 RELEASED, DEPRECATED

triggerFullApproveCalcDataPipeline 2402 v1 RELEASED, DEPRECATED

triggerFullCompAndPayPipeline 2402 v1 RELEASED, DEPRECATED

triggerValidateAndTransferTxnOrder- 2402 v1 RELEASED, DEPRECATED

sCredits

triggerXDLJob 2402 v1 RELEASED, DEPRECATED

Related Information

SAP Automation Pilot Integration: Downloads [page 499]

Importing the Default Core Catalog for SAP SuccessFactors Incentive Management [page 451]

Incentive Management Admin Design Guide

502 PUBLIC Integration
28.3.9.2 Download Core Catalog Inputs

Click here to download the following Core Catalog Inputs:

Incentive Management Re- FLAGS (*use latest if depre-

INPUT NAME lease Version Command File Version cated)

globalConfig 2405 v1 RELEASED

ANSConnection 2402 v1 RELEASED

serviceAccountCredentials 2402 v1 RELEASED

Related Information

SAP Automation Pilot Integration: Downloads [page 499]

Importing the Default Core Catalog for SAP SuccessFactors Incentive Management [page 451]

28.3.9.3 Download Tenant Catalog Commands

Click here to download the following Tenant Catalog Commands:

Incentive Management Re- FLAGS (*use latest if depre-

COMMAND NAME lease Version Command File Version cated)

execModelRunPipeline.json 2411 v1 RELEASED

execPositionsApproveCalc- 2411 v1 RELEASED

DataPipeline.json

execPositionsCompAndPay- 2411 v1 RELEASED

Pipeline.json

syncAllModels.json 2411 v1 RELEASED

monitorSFTPDirectory 2407 v2 RELEASED

execXDLDataExtract 2407 v4 RELEASED

execValidateAndTransferTx- 2407 v4 RELEASED

nOrderCreditsPipeline

execValidateAndTransfer- 2407 v1 RELEASED

PlanRelatedDataPipeline

execValidateAndTransferOr- 2407 v1 RELEASED

ganizationDataPipeline

execValidateAndTransfer- 2407 v1 RELEASED

ClassificationDataPipeline

Incentive Management Admin Design Guide

Integration PUBLIC 503
 Incentive Management Re- FLAGS (*use latest if depre-
COMMAND NAME lease Version Command File Version cated)

execResetFromValidatePipe- 2407 v3 RELEASED

line

execResetFromClassifyPipe- 2407 v2 RELEASED

line

execFullCompAndPayPipe- 2407 v3 RELEASED

line

execFullApproveCalcDataPi- 2407 v3 RELEASED

peline

execEXTStoredProcedure 2407 v3 RELEASED

execDataSphereTaskChain 2407 v5 RELEASED

execDataSphereTaskChain 2405 v4 RELEASED, DEPRECATED

execValidateAndTransferTx- 2405 v3 RELEASED, DEPRECATED

nOrderCreditsPipeline

execResetFromValidatePipe- 2405 v2 RELEASED, DEPRECATED

line

execDataSphereTaskChain 2405 v3 RELEASED, DEPRECATED

execXDLDataExtract 2405 v3 RELEASED, DEPRECATED

execDataSphereTaskChain 2405 v2 RELEASED

execEXTStoredProcedure 2405 v2 RELEASED, DEPRECATED

execFullApproveCalcDataPi- 2405 v2 RELEASED, DEPRECATED

peline

execFullCompAndPayPipe- 2405 v2 RELEASED, DEPRECATED

line

execValidateAndTransferTx- 2405 v2 RELEASED, DEPRECATED

nOrderCreditsPipeline

execXDLDataExtract 2405 v2 RELEASED, DEPRECATED

smartBatchNameDetection 2405 v2 RELEASED

smartPeriodDetection 2405 v2 RELEASED

syncAllCalendars 2405 v2 RELEASED

syncAllMasterData 2405 v2 RELEASED

syncAllPeriods 2405 v2 RELEASED

syncAllPeriodTypes 2405 v2 RELEASED

syncAllProcessingUnits 2405 v2 RELEASED

execEXTStoredProcedure 2405 v1 RELEASED, DEPRECATED

monitorSFTPDirectory 2405 v1 RELEASED, DEPRECATED

execDataSphereHANAQuery 2405 v1 RELEASED

Incentive Management Admin Design Guide

504 PUBLIC Integration
 Incentive Management Re- FLAGS (*use latest if depre-
COMMAND NAME lease Version Command File Version cated)

execResetFromClassifyPipe- 2405 v1 RELEASED, DEPRECATED

line

execResetFromValidatePipe- 2405 v1 RELEASED, DEPRECATED

line

execDataSphereTaskChain 2402 v1 RELEASED, DEPRECATED

execFullApproveCalcDataPi- 2402 v1 RELEASED, DEPRECATED

peline

execFullCompAndPayPipe- 2402 v1 RELEASED, DEPRECATED

line

execValidateAndTransferTx- 2402 v1 RELEASED, DEPRECATED

nOrderCreditsPipeline

execXDLDataExtract 2402 v1 RELEASED, DEPRECATED

smartBatchNameDetection 2402 v1 RELEASED, DEPRECATED

smartPeriodDetection 2402 v1 RELEASED, DEPRECATED

syncAllCalendars 2402 v1 RELEASED, DEPRECATED

syncAllMasterData 2402 v1 RELEASED, DEPRECATED

syncAllPeriods 2402 v1 RELEASED, DEPRECATED

syncAllPeriodTypes 2402 v1 RELEASED, DEPRECATED

syncAllProcessingUnits 2402 v1 RELEASED, DEPRECATED

Related Information

SAP Automation Pilot Integration: Downloads [page 499]

Importing the Default Tenant Specific Catalog for SAP SuccessFactors Incentive Management [page 457]

28.3.9.4 Download Tenant Catalog Inputs

Click here to download the following Tenant Catalog Inputs:

Incentive Management Re- FLAGS (*use latest if depre-

INPUT NAME lease Version Command File Version cated)

SFTPConnection 2405 v1 RELEASED

DataSphereHANAConnec- 2405 v1 RELEASED

tion

DataSphereConnection 2402 v1 RELEASED

Incentive Management Admin Design Guide

Integration PUBLIC 505
 Incentive Management Re- FLAGS (*use latest if depre-
INPUT NAME lease Version Command File Version cated)

SFIMConnection 2402 v1 RELEASED

calendars 2402 v1 RELEASED

periodTypes 2402 v1 RELEASED

periods 2402 v1 RELEASED

processingUnits 2402 v1 RELEASED

Related Information

SAP Automation Pilot Integration: Downloads [page 499]

Importing the Default Tenant Specific Catalog for SAP SuccessFactors Incentive Management [page 457]

28.4 Integration with SAP Data Custodian

SAP Data Custodian's Key Management Service provides Customer-Controlled Encryption Key (CCEK)
functionality, which allows you to create and manage keys directly in your Data Custodian Key Management
Service (KMS) tenant. SAP Data Custodian’s Key Management Service (KMS) enables you to have full control
over your encryption key used for the encryption of your SAP SuccessFactors Incentive Management data
stored in SAP HANA.

This integration empowers you to maintain visibility, control, and encryption of your data in the cloud.

 Note

A separate license to SAP Data Custodian is required in order to use this capability with SAP
SuccessFactors Incentive Management.

To enable the CCEK functionality on your tenant:

1. Create a service request to enable CCEK encryption on your tenant.

2. Enable and connect the service in SAP Data Custodian.

Create a service request to enable CCEK encryption on your tenant

1. Log on to SAP for Me .

2. Create a service request for SAP SuccessFactors Incentive Management: KMS LSS SETUP.
3. Select the SAP SuccessFactors Incentive Management tenant for which you want to switch over from
default encryption to customer-controlled encryption.

Incentive Management Admin Design Guide

506 PUBLIC Integration
  Note

Pay close attention to the SAP SuccessFactors Incentive Management tenant you choose. Once
you switch over to customer-controlled encryption for a SAP SuccessFactors Incentive Management
tenant, reverting to SAP-managed encryption cannot be done.

4. Enter the E-mail Address of the key admin who will be responsible for managing the key. If you want to add
more key admins, choose the plus icon (+).
5. Enter the KMS Tenant ID. If you don't know your KMS tenant ID, your key admin can retrieve it for you from
SAP Data Custodian.
6. Click Review, select the confirmation box, and click Submit. This will notify the key admins via e-mail to
accept the connection request in KMS.

 Note

The lead time of the process depends on multiple factors including service request load and user
interaction time, but in most cases, it takes approximately 10 minutes. However, if the key admin
doesn’t act on the request in 5 days, the process will be cancelled. In this case, you’ll need to create
another request. When the switch-over is successfully completed, the creator of the service request
receives a notification e-mail.

Enable and connect the service in SAP Data Custodian

1. Log in to SAP Data Custodian as the key admin.

2. Click on the SAP SuccessFactors Incentive Management tile on the Key Management Service Dashboard.
3. Choose Create Group.
1. Enter the group name. Specify the Description, Landscape, System ID, and Tenant as needed.
2. Choose Step 2.
3. Select the Key Store from the drop-down.
4. Select the Key Store Region from the drop-down.
5. Click Create. After the group is created, a confirmation message is displayed stating that the group is
successfully created.
4. Choose Create Key.
1. Enter Key Name and an optional Key Description.
2. Click Step 2.
3. Select Yes for Create KMS Master Key.
4. For Creation Properties, select RSA.
5. For RSA Properties, select 4096.
6. For Key Operations, select Encrypt and Decrypt.
7. Click Review.
8. Click Create to proceed. A message is displayed stating that the Encryption Key is successfully
created.
5. Click Users.
1. Click Technical Users.
2. Click Create Technical User.

Incentive Management Admin Design Guide

Integration PUBLIC 507
 3. Provide the Username and click on Step 2.
4. Select Yes for Create HANA Technical User.
5. Click Step 3.
6. Specify Active Time Range as needed.
7. Click Step 4.
8. Click Review.
9. Click Create. A message is displayed stating that the Technical User is successfully created.
6. Click Connect Service.
1. Select the tenant you want to connect.
2. Click Connect to proceed. The State is updated to display Complete if the service is connected
successfully.

After you’ve switched over to customer-controlled encryption, SAP can no longer be held responsible for
service downtime or data loss if you do any of the following:

• Disable your key

• Disable your technical user
• Delete your key
• Delete your technical user
• Delete your technical user credentials

Deleting your key, technical user, or technical user credentials cannot be reversed and might lead to data loss.
Disabling your key or technical user can be reversed by your assigned key admin.

See SAP Data Custodian documentation for more details.

28.5 API Authentication

• Service Account Authentication [page 508]

• User Authentication Using JWT token [page 513]

28.5.1 Service Account Authentication

For system to system authentication, the best practice is to use service accounts (instead of user accounts).
This topic describes service account authentication.

To log in as a service account, you must use the OIDC client credentials flow.

1. Create the OpenId Connect application on SAP IAS for the external service (one OIDC application per
service account).
1. Go to IAS administration → Applications & Resources → Applications and click Create to create a
new IAS application.

Incentive Management Admin Design Guide

508 PUBLIC Integration
 2. Choose OpenId Connect for Application Protocol.

3. Go to OpendID Connect Configuration and enter Name property.

Incentive Management Admin Design Guide

Integration PUBLIC 509
 4. In Client Authentication, add the client secret or certificate for API Authentication that will be used for
basic or MTLS authentication.

5. In Attributes, add aud as the attribute.

• Get the clientId from the Incentive Management OpenId Connect application. (There is one
Incentive Management OIDC Application per tenant.). Go to IAS administration → Applications
and open Incentive Management OIDC application.
The naming pattern is as follows: COMM_{SUBDOMAIN}_OIDC_{TENANTURL}. The
Incentive Management OIDC app name example is as follows: COMM_SUB1_OIDC_https://
sub1.<commissions_domain.
Open Client Authentication configuration and copy the client id. Client ID Configuration is
illustrated below.

• Go to the newly created IAS OIDC Application → Default Attributes and create a new default
attribute with name aud and value as clientId as described in the previous step (i.e. client id
from the Commissions COMM_{SUBDOMAIN}_OIDC_{TENANTURL} OIDC application. The Aud
attribute configuration is illustrated below.

Incentive Management Admin Design Guide

510 PUBLIC Integration
2. Go to Incentive Management Admin > Security > Service Accounts > Create.
• Client Id is the same clientId that is specified in the newly created OIDC application (see step 1)
• In Groups, select Incentive Management Admin groups for service account. If you want your service
account to have all Incentive Management permissions assigned, choose Administrator group from
drop-down.
• In Roles, select the specific roles that you want to assign to this service account. If you want your
service account to have all permissions assigned, choose Sales Portal Administrator

3. To get the JWT token (access token), send POST request to https://<sap_ias_hostname>/oauth2/token.
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Base64 encoded ClientID:ClientSecret>
(ClientID is the clientId of the newly created OIDC application from step 1, and ClientSecret is the secret
generated in step 1.d.
Example: Authorization: Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0
Body:
grant_type: client_credentials
client_id: type client id of the newly created IAS OIDC application from step 1
You can also use certificates instead of client secret to authenticate.

Incentive Management Admin Design Guide

Integration PUBLIC 511
 Client Credentials Authentication Flow Header:

Client Credentials Authentication Flow Body:

Response example:

 Sample Code

{
"access_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovLzxzYXBfaWFzX2hvc
3RuYW1lPiIsImlhdCI6MTY3NzY2MTIyNywiZXhwIjoxNzA5MTk3MjI3LCJhdWQiOlsiM2NhZjJl
MTktZmQ1Yi00NzRkLWE4ZDQtMzA0MGIyZmFjYTdlIiwiNmRiMzZlZGEtNTBiZS00MTgzLTgwOTI
tZTUxZTRmZTcwYzBhIl0sInN1YiI6IjNjYWYyZTE5LWZkNWItNDc0ZC1hOGQ0LTMwNDBiMmZhY2
E3ZSJ9.i168I2o4y-epbMog_LGkoYdCscXuFZgN67E_zyF-oVk",
"token_type": "Bearer",
"expires_in": 3600
}

4. The received JWT token needs to be sent as the Authorization Bearer header in the Commissions API
request. Authorization header should look like this:Bearer access_token_from_IAS_response
Authorization header example:

 Sample Code

Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovLzxzYXBfaWFzX2hvc3
RuYW1lPiIsImlhdCI6MTY3NzY2MTIyNywiZXhwIjoxNzA5MTk3MjI3LCJhdWQiOlsiM2NhZjJlM
TktZmQ1Yi00NzRkLWE4ZDQtMzA0MGIyZmFjYTdlIiwiNmRiMzZlZGEtNTBiZS00MTgzLTgwOTIt
ZTUxZTRmZTcwYzBhIl0sInN1YiI6IjNjYWYyZTE5LWZkNWItNDc0ZC1hOGQ0LTMwNDBiMmZhY2E
3ZSJ9.i168I2o4y-epbMog_LGkoYdCscXuFZgN67E_zyF-oVk

Incentive Management Admin Design Guide

512 PUBLIC Integration
28.5.2 User Authentication Using JWT token

Overview

1. Make sure you have the clientId/clientSecret (or the client certificate) from the IAS OIDC application. If you
don't have the required details, contact the IAS administrator for the required details or set your existing
certificate as client certificate. See Create Client Secret (Only for IAS Admins) [page 513] or Set Client
Certificate (Only for IAS Admins) [page 515] for more details.
2. To get the JWT token from SAP IAS, use the OIDC password credentials flow. The clientId/clientSecret (or
the client certificate) and userId/password will be required. See Get JWT Token from IAS [page 517] for
more details.
3. Use the ID token for accessing the Incentive Management API. You can get the ID token from the response
and use it in the Authorization Bearer header to call the API. See Call Incentive Management API with
Bearer Token [page 521] for more details.

28.5.2.1 Create Client Secret (Only for IAS Admins)

Perform the following steps to create the client secret:

1. Go to IAS Administration → Applications and open Commissions OIDC application.

To create Commissions OIDC applications, we use the following naming pattern:
COMM_{SUBDOMAIN}_OIDC_{TENANTURL}.
IAS administration application URL example: https://<sap_ias_hostname>/admin/#/applications/
NO_APPLICATION_SELECTED
Commissions OIDC app name example:
COMM_SUB1_OIDC_https://sub1.<commissions_domain>
2. Open Client ID, Secrets, and Certificates configuration. See the below example:

Incentive Management Admin Design Guide

Integration PUBLIC 513
3. Add a new secret and copy the clientId and the clientSecret from the result prompt.

Provide the required details in the Add Secret dialog and click Save.

Save your client secret and click OK.

Incentive Management Admin Design Guide

514 PUBLIC Integration
28.5.2.2 Set Client Certificate (Only for IAS Admins)

Perform the following steps to set client certificate:

1. Go to IAS Administration → Applications and open Commissions OIDC application.

To create Commissions OIDC applications, we use the following naming pattern:
COMM_{SUBDOMAIN}_OIDC_{TENANTURL}.
IAS administration application URL example: https://<sap_ias_hostname>/admin/#/applications/
NO_APPLICATION_SELECTED
Commissions OIDC app name example:
COMM_SUB1_OIDC_https://sub1.<commissions_domain>
2. Open Client ID, Secrets, and Certificates configuration.

3. Add the Certificate for the API Authentication.

Incentive Management Admin Design Guide

Integration PUBLIC 515
4. Generate a new certificate or upload the certificate using file or insert a certificate as text.

Certificate Formats

If you choose to generate a new certificate, it will be download in .p12 format.

To export the .p12 format as .PEM format (public and private key included in one file) use following command:

 Sample Code

openssl pkcs12 -in cert.p12 -out key-cert.pem -nodes -passin

pass:PasswordYouChoseWhileGeneratingCert

Incentive Management Admin Design Guide

516 PUBLIC Integration
To export the .p12 format as .crt and .key format (private and public key in separate files), use the following
command:

 Sample Code

openssl pkcs12 -nodes -in cert.p12 -nocerts -out private.key -passin

pass:PasswordYouChoseWhileGeneratingCert
openssl pkcs12 -in cert.p12 -clcerts -nokeys -out public.crt -passin
pass:PasswordYouChoseWhileGeneratingCert

If you choose to upload a certificate, you must provide a file in .crt or .cer format.

 Note

Two different IAS applications cannot have same client certificate.

28.5.2.3 Get JWT Token from IAS

In order to get the JWT token to set as the Bearer authorization header for SAP SuccessFactors Incentive
Management API authentication, you must use the OIDC password credentials flow. See Configure the Client to
Call Identity Authentication Token Endpoint for Resource Owner Password Credentials Flow for more details on
SAP IAS password credentials flow.

To get the JWT token, send POST request to https://<sap_ias_hostname>/oauth2/token:

This API is private so you must provide required authentication details in order to get the JWT token back.

Authentication can be performed in the following two ways:

• using clientId and client secret (packing these into the Basic authorization header)
• using client certificate

Using clientId and clientSecret

Perform the following steps:

1. Prepare Basic authorization header for calling IAS oauth2 token API endpoint.
Write client id and client secret in following format:
ClientID:clientSecretand base64 encode it. Generated base64 encoded string is used as basic token
for the Authorization header.
Authorization header should look like this:
Basic base64Encode(ClientID:ClientSecret)
Authorization header example:
Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0
2. Send POST request to https://<sap_ias_hostname>/oauth2/token:
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: prepared header from step 1 - Basic base64Encode(ClientID:ClientSecret)

Incentive Management Admin Design Guide

Integration PUBLIC 517
 Body:

 Sample Code

grant_type: password
client_id: type client id of the IAS OIDC application
username: type username that you use to login on SAP IAS
password: type password that you use to login on SAP IAS

All params must be URL encoded.

 Sample Code

POST https://<sap_ias_hostname>/oauth2/token
Headers:
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0
Body:

grant_type=password&client_id=test_client_id&username=john.doe%40example.co
m&password=test_password

-------------------node js node-fetch example-----------------------

const params = new URLSearchParams();
params.append('grant_type', 'password');
params.append('username', '[email protected]');
params.append('password', 'test-password');
params.append('client_id', 'test_client_id');
const headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0'
};
const response: Response = await fetch(
'https://<sap_ias_hostname>/oauth2/token',
{
method: 'POST',
body: params,
headers: headers,
}
);

Headers Example: The below screenshot illustrates IAS /oauth2/token endpoint for authentication and
access token retrieval.

Parameters/Body Example: The below example illustrates the IAS /oauth2/token endpoint for
authentication and access token retrieval.

Incentive Management Admin Design Guide

518 PUBLIC Integration
3. Extract id_token from the response.

 Sample Code

{
"access_token":
"YzBhZGVlMzYtYzc3NC00ZDczLWExODAtMGQ2YTllZjU0Mjg5S2VCcHpWXzdFczl6QVJmazFNNG
ZqYUVnMFBRdzhlcnp6M1pIYVJFcFpsMA",
"refresh_token": "30e78d3c9501ff498d505fa240fc9269",
"id_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovLzxzYXBfaWFzX2hvc
3RuYW1lPiIsImlhdCI6MTY3NzY2MTIyNywiZXhwIjoxNzA5MTk3MjI3LCJhdWQiOlsiMTJzNTR3
NmEtMXc1Ni01ZThiLWYyNTYtMDd2MDV2ZmdiMzEyIiwiYjAwNWNiMjYtYjQwZS00Nzg2LTk1Y2Q
tNzIyYTc5YTRjMGI1Il0sInN1YiI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIiwiZmlyc3ROYW1lIj
oiSm9obiIsImxhc3ROYW1lIjoiRG9lIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsI
nVzZXJJZCI6Ik0wMDAwMDEifQ.EnIBD9u8jbl0_xb53pEjov9gLSLWjCPgHc3PeOM7DKg",
"token_type": "Bearer",
"expires_in": 3600
}

Using Client Certificate

When you choose to authenticate using client certificates, instead of using authorization header, you need to
send registered certificate as part of your request. Both public and private keys need to be sent in the request.
How you send the certificate depends on the http client that you are using (for example, when you use curl, you
need to specify the path to certify the file in .PEM format).

Perform the following steps:

1. Send POST request to https://<sap_ias_hostname>/oauth2/token:

Headers:
Content-Type: application/x-www-form-urlencoded
Body:
grant_type=password&username=<userIdentifier>&password=<password>&clientId=<clientId>

 Sample Code

grant_type: password
username: type username that you use to login on SAP IAS
password: type password that you use to login on SAP IAS
client_id: type client id of the IAS OIDC application

Cert:

Incentive Management Admin Design Guide

Integration PUBLIC 519
 public key in .crt format
Key:
private key in .key format
(or .PEM format with both public and private keys together, depends on the http client)
All params should be URL encoded.

 Note

The certificate and key can be used as separate .pem files rather than specifically .crt and .key files.
Their inclusion in requests is dependent on the HTTP client used, and manual addition may be
required.

 Sample Code

POST https://<sap_ias_hostname>/oauth2/token
Headers:
Content-Type: application/x-www-form-urlencoded
Body:

grant_type=password&client_id=test_client_id&username=john.doe%40example.co
m&password=test_password
Cert: "-----BEGIN CERTIFICATE-----\n BASE64CERT \n-----END CERTIFICATE-----
\n"
Key: "-----BEGIN PRIVATE KEY-----\n BASE64KEY \n-----END PRIVATE KEY-----
\n"
-------------------node js node-fetch example-----------------------
const params = new URLSearchParams();
params.append('grant_type', 'password');
params.append('username', '[email protected]');
params.append('password', 'test-password');
params.append('client_id', 'test_client_id');
const options = {
method: 'POST',
body: params,
headers: {'Content-Type': 'application/x-www-form-urlencoded'},
agent : new https.Agent({
cert: "-----BEGIN CERTIFICATE-----\n BASE64CERT \n-----END
CERTIFICATE-----\n",
key: "-----BEGIN PRIVATE KEY-----\n BASE64KEY \n-----END PRIVATE
KEY-----\n"
})
};
const response: Response = await fetch(
'https://<sap_ias_hostname>/oauth2/token',
options,
);

2. Extract id_token from the response. The response example is as below:

 Sample Code

{
"access_token":
"YzBhZGVlMzYtYzc3NC00ZDczLWExODAtMGQ2YTllZjU0Mjg5S2VCcHpWXzdFczl6QVJmazFNNG
ZqYUVnMFBRdzhlcnp6M1pIYVJFcFpsMA",
"refresh_token": "30e78d3c9501ff498d505fa240fc9269",
"id_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovLzxzYXBfaWFzX2hvc
3RuYW1lPiIsImlhdCI6MTY3NzY2MTIyNywiZXhwIjoxNzA5MTk3MjI3LCJhdWQiOlsiMTJzNTR3
NmEtMXc1Ni01ZThiLWYyNTYtMDd2MDV2ZmdiMzEyIiwiYjAwNWNiMjYtYjQwZS00Nzg2LTk1Y2Q
tNzIyYTc5YTRjMGI1Il0sInN1YiI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIiwiZmlyc3ROYW1lIj
oiSm9obiIsImxhc3ROYW1lIjoiRG9lIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsI
nVzZXJJZCI6Ik0wMDAwMDEifQ.EnIBD9u8jbl0_xb53pEjov9gLSLWjCPgHc3PeOM7DKg",

Incentive Management Admin Design Guide

520 PUBLIC Integration
 "token_type": "Bearer",
"expires_in": 3600
}

28.5.2.4 Call Incentive Management API with Bearer Token

This topic illustrates how to call the Incentive Management API with the Bearer token.

When you get the ID token from the IAS, you can use it as the Bearer Authorization header for accessing
Incentive Management API.

The authorization header should look like this: Bearer id_token_from_IAS_response

 Sample Code

curl --location --request GET 'https://<commissions_hostname>/mtsvc/tcmp/

rest/v2/participants' \
--header 'Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovLzxzYXBfaWFzX2hvc3RuY
W1lPiIsImlhdCI6MTY3NzY2MTIyNywiZXhwIjoxNzA5MTk3MjI3LCJhdWQiOlsiMTJzNTR3NmEtMXc
1Ni01ZThiLWYyNTYtMDd2MDV2ZmdiMzEyIiwiYjAwNWNiMjYtYjQwZS00Nzg2LTk1Y2QtNzIyYTc5Y
TRjMGI1Il0sInN1YiI6ImpvaG4uZG9lQGV4YW1wbGUuY29tIiwiZmlyc3ROYW1lIjoiSm9obiIsImx
hc3ROYW1lIjoiRG9lIiwiZW1haWwiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsInVzZXJJZCI6Ik0wM
DAwMDEifQ.EnIBD9u8jbl0_xb53pEjov9gLSLWjCPgHc3PeOM7DKg'

Incentive Management Admin Design Guide

Integration PUBLIC 521
29 Data Integration and Management
Solutions

This section provides information about the data integration and management solutions that SAP
SuccessFactors Incentive Management currently provides. It is intended to help customers and partners
analyze each offering and pick the one that suits their business requirement.

Data Integration and Management Solutions for HANA

SAP SuccessFactors Incentive Management currently offers the following data integration and management
solutions for HANA:

• Excel Data Loaders

• Express Data Loader
• Smart Data Integration (SDI)
• SAP Integration Suite (also known as SAP Cloud Integration)
• REST API

SAP Inte-
Data Integration Smart Data Integra- gration
Solutions Excel Data Loaders Express Data Loader tion (SDI) Suite REST API

Purpose/ Routine data man- High volume batch load High volume load API to API For cus-
agement with data transforma- integration tom API
Use Case tions client

User Type Business User Technical User Technical User Technical Technical
User User

Usage Frequency Ad-hoc Ad-hoc or Scheduled Scheduled or Real Scheduled Real Time
or Real
Time
Time

Data Volume < 1,000 rows Up to 10 million records or Higher volume than 1,000– < 1,000
1-GB data per drop file Express Data Loader 100,000 rows per
rows call

Data Transforma- None HANA stored procedures Flowgraph based Integration None
tions transformations
Flow (IFlow)

Incentive Management Admin Design Guide

522 PUBLIC Data Integration and Management Solutions
 SAP Inte-
Data Integration Smart Data Integra- gration
Solutions Excel Data Loaders Express Data Loader tion (SDI) Suite REST API

Connectors Not Applicable Not Applicable In-built adapters / Open Con- Not Appli-
connectors for nectors ca- cable
source systems pability
within SAP
Integration
Suite
(api.sap.co
m)

Licenses Included in Included in SAP Included in Requires Included

SAP SuccessFactors SuccessFactors Incentive SAP SuccessFactors additional li- in SAP
Incentive Management Incentive cense SuccessF
Management Management actors
Incentive
Managem
ent

What data can be All master data and Read access to production Read access to pro- Access to Access to
accessed?
transaction data can data (TCMP schema) is pro- duction data (TCMP supported sup-
be accessed. vided. schema) is provided. APIs, such ported
as get cred- APIs,
Data upload /down- Read access via replica- Read access via rep-
its, transac- such as
load is supported. tion to custom table (EXT lication to custom ta-
tions, etc. is get cred-
schema) is supported. ble (EXT schema) is
allowed. its, trans-
supported.
Write access to EXT schema actions,
APIs for cre-
requires approval from the Write access to stage etc. is al-
ating data,
SAP support team. tables is provided. lowed.
such as
credits, APIs for
transaction, creating
etc. are sup- data,
ported. such as
credits,
transac-
tion, etc.
are sup-
ported.

Incentive Management Admin Design Guide

Data Integration and Management Solutions PUBLIC 523
 SAP Inte-
Data Integration Smart Data Integra- gration
Solutions Excel Data Loaders Express Data Loader tion (SDI) Suite REST API

How data can be Through corre- Customer/ Partner engi- Customer/ Partner Customer/ Data can
accessed? sponding workspace be ac-
neering team must build engineering team Partner en-
in the UI cessed
HANA artifacts in dev/ test must build SDI arti- gineering
using any
environment. facts in dev/ test en- team must integra-
vironment. build map- tion tool
Once artifacts are ready to
ping using that sup-
deploy in production, the Once artifacts are
Open Con- port API
SAP support team can repli- ready to deploy in calls.
nectors.
cate the same in the produc- production, the SAP
tion environment. support team must Pre-pack-
replicate the same aged IFlows
Once the artifacts are repli-
in production envi- from Suc-
cated in production environ-
ronment. cessFactors
ment, users can initiate the
- SAP
data loading process by run- Once the artifacts
SuccessFac
ning pipeline and Express are replicated in pro-
tors
Data Loader jobs. duction environment,
Incentive
customers can trig-
SFTP pull from drop box Managemen
ger data retrieval
to customer network is per- t must be
when needed.
formed. used.

Customers
must build
the custom
IFlows to
bring their
data to SAP
SuccessFac
tors
Incentive
Managemen
t using
API's.

Once the
mapping is
ready to de-
ploy in pro-
duction,
replicate the
mapping to
production
environ-
ment.

A SFTP pull
from the

Incentive Management Admin Design Guide

524 PUBLIC Data Integration and Management Solutions
 SAP Inte-
Data Integration Smart Data Integra- gration
Solutions Excel Data Loaders Express Data Loader tion (SDI) Suite REST API

Dropbox to
the custom-
er's network
is per-
formed.

Integration
Flow (IFlow)
triggers
data to send
SFTP Drop-
box to con-
tinue to
process
through Ex-
press Data
Loader
Jobs.

Benefits Business user- Parallel processing of files is High volume data User- No VPN
access is
friendly. supported. load and extract is friendly, in-
needed.
supported. tuitive, and
No VPN access is No VPN access is needed.
Web-based Custom-
needed. Supports all common
UI is availa- ers can
styles of data deliv-
ble. custom-
ery: Batch, Real Time,
ize the
and Virtualization. No VPN ac-
JSON re-
cess is
High performance sults out-
needed.
in-memory process- put to suit
ing platform is sup- their indi-
ported. vidual
business
No VPN access is
needs.
needed.
Tasks can
be auto-
mated via
APIs.

Things to consider Data limits apply. The SAP support team must The SAP support - API limits
be involved in certain opera- team must be in- apply.
tions. Additional costs may volved in certain op-
apply. erations. Additional
costs may apply.

Incentive Management Admin Design Guide

Data Integration and Management Solutions PUBLIC 525
30 Downloading SAP HANA Studio

SAP HANA studio enables technical users to manage the SAP HANA database, to create and manage user
authorizations, and to create new or modify existing models of data in the SAP HANA database.

To download SAP HANA Studio:

1. Go to the launchpad: https://launchpad.support.sap.com/#/softwarecenter/

 Note

You will need the S-user ID to log in to the launchpad.

2. In the search field, select Downloads and enter SAP HANA Studio.
3. Select SAP HANA STUDIO 2 to download.
4. Use sapcar to extract the sar file. The installation does not require a license key.

 Note

SAP HANA Studio can also be downloaded from https://tools.hana.ondemand.com/. This site allows you
to install various SAP development tools.

Related Information

SAP HANA Studio

Incentive Management Admin Design Guide

526 PUBLIC Downloading SAP HANA Studio
31 Known Limitations

In order to keep your SAP SuccessFactors Incentive Management platform functioning at optimal
performance, we’ve captured the limitations that must be considered when configuring, managing, and using
the product.

See the Known Limitations document for details.

The purpose of this document is to help you make smarter approaches toward processing incentives by
avoiding issues that are known to cause problems. Over time, our team will continue to improve the SAP
SuccessFactors Incentive Management platform to further enhance customer satisfaction.

31.1 Known Issues

Specific release-related Known Issues (if any) are listed in the What's New and are also listed in the Known
Limitations [page 527] document.

Incentive Management Admin Design Guide

Known Limitations PUBLIC 527
Important Disclaimers and Legal Information

Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:

• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:

• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.

• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using
such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.

Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,
genders, and abilities.

Incentive Management Admin Design Guide

528 PUBLIC Important Disclaimers and Legal Information
Incentive Management Admin Design Guide
Important Disclaimers and Legal Information PUBLIC 529
www.sap.com/contactsap

© 2025 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.

SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN