You are here:
Monetary Cap
Track actual, estimated, committed, and total expenses across managed events, and enforce spending limits on the participant’s expenses. Monetary caps are account-level restrictions that apply when a user creates a Managed Event Participant record or an Expense Participant record.
Required Editions
| Available in: Lightning Experience |
| Available in: Enterprise and Unlimited Editions with Life Sciences Cloud, Life Sciences Cloud for Customer Engagement Add-on license, and the Life Sciences Customer Engagement managed package. |
Prerequisites
- Activate the monetary cap trigger handlers.
- To see all the active monetary caps related to a participant's account, add the Utilization Tracker Lightning App Builder component onto the Account record page.
How Monetary Cap Works
Monetary Cap calculates expense amounts for three expense buckets:
- Estimated expenses: The amount of money that’s projected to be spent for one or more activities.
- Committed expenses: The amount of money that’s approved for one or more activities.
- Actual expenses: The amount of money that’s already expensed for one or more activities.
While an event is in progress, the system takes the higher of actual expenses versus the sum of estimated and committed expenses as the running total. Once an event is closed, the system considers only the actual expenses.
Each participant account has a spending limit defined in a Provider Activity Goal Limit record. Whenever a participant is added to an event, or an expense is created, updated, or deleted, the system automatically recalculates the cap total and checks it against that limit. Only expenses whose type is marked Included in Cap count toward the limit.
When a limit is breached, the system responds in one of two ways, depending on how the cap is configured:
- Error: The action is blocked, with an error message, preventing the participant from being added or the expense from being recorded.
- Warn: The action is allowed, but a Managed Event Participant Discrepancy record is created with a warning message.
Calculation of Total Expense
The total expenses are calculated based on the managed event’s status.
If the managed event is completed, that is, the status represents a concluded state, the total expenses equal the actual expenses.
Total = Actual
If the managed event is not completed, that is, the status represents a draft state, the total expenses are the maximum of actual expenses and estimated plus committed expenses.
Total = MAX(Actual, Estimated + Committed)
The cap data is stored in the provider activity goal measure’s additional information field in JSON format and is rolled up into Committed Expense Amount, Actual Expense Amount, Estimated Expense Amount, and Total Expense Amount fields.
The following code is an example of a monetary cap.
{"1POXJOO0000002L4AU":{"isFinalValue":true,"isFinal":true,"estimatedMap":
{},"estimated":{},"committedMap":{},"committed": {},"actualMap":
{"1Z6XJ0000000iAjOAI":{"rate": 1.0,"amount":200.0},"1Z6XJ00000001970AA":
{"rate":1.0,"amount": 100.0}},"actual":{"1Z6XJ0000000iAjOAI":
{"rate": 1.0,"amount":200.0},"1Z6XJ00000001970AA":
{"rate": 1.0, "amount":100.077}}}}The cap is calculated only after the managed event is in a final state, that is, it’s closed or has been concluded. The final status is determined based on the Concluded Event Status field in the event management org-level settings. The conversion rates are automatically updated based on the currency.
Trigger Handlers
- ExpenseParticipantMonetaryCapsHandler
- When expense participants are created, the handler recalculates total expenses. The handler blocks expense participants from being created if the monetary cap is set up with Alert Type as Error and the new total exceeds the monetary limit. If the Alert Type is Warn, even if the monetary limit is exceeded, the handler allows the creation of an expense participant but with a warning. Only participants whose expense type is marked as Included in Cap are counted.
- When an expense participant’s amount is updated, the handler recalculates cap totals based on the new amount. If the monetary cap’s Alert Type is set up as Error, the handler blocks amount increases that would push the total over the cap. If the Alert Type is Warn, even if the monetary limit is exceeded, the handler allows the amount to increase. Decreases are always allowed without restriction — even if the current total is already over the cap — because they reduce utilization. Changes to any field other than amount trigger no recalculation at all.
- When an expense participant is deleted, the handler recalculates cap totals to remove the deleted amount. Deletions are always allowed because removing a participant always reduces the cap total.
- MngEventPartMonetaryCapsHandler
- When a new participant is being added to an event, the handler checks whether that provider’s spending cap has already been reached. If the monetary cap is set up with Alert Type as Error, the handler restricts the addition. If the monetary cap is set up with Alert Type as Warn, the handler allows it but with a warning.
- When the participant account is changed (account to account, account to expert, or expert to account), the handler recalculates caps for both the old and new participant. If an account is swapped with a user, the monetary cap is reduced only for the account. Swapping between non-account types (user, contact) has no effect.
- MngEventMonetaryCapsHandler
- If the managed event status is updated, the trigger handler recalculates the monetary cap limit for all the participants. If the status is not one of the qualifying statuses (draft or closed), the handler removes the expense entry and the event is no longer tracked.
- If the managed event start date is updated to outside the associated activity plan’s time period, the handler removes the expense entry. If the event dates are within the activity plan time period, the handler recalculates the expense based on the new time period.
- If the managed event is deleted, the handler removes all the related contributions from the monetary cap limit.
- ExpenseMonetaryCapsHandler
- If the expense date is updated, the handler recalculates cap totals based on the new date. If the new date falls outside a configured time window, the expense no longer counts toward the cap.
- If any of the controlling fields defined in the ProviderActivityMeasureType’s Criteria JSON is updated but still meets the criteria, the handler recalculates the cap. If any of the controlling fields defined in the ProviderActivityMeasureType’s Criteria JSON is updated but fails to meet the criteria, the handler removes the contribution from the cap total.
- If an expense that’s marked as Included in Cap is deleted, the handler recalculates the expense and removes the expense’s entry. Only expenses whose type is marked as Included in Cap are counted.
Batch Jobs
- Calculate Expenses Against Monetary Caps: When data is uploaded in bulk, trigger handlers are this batch job recalculates expenses based on the latest account data.
- Share Provider Activity Goals Based on Activity Plan Type: Shares provider activity goals that are associated with activity plans of type Event Management Limit with the territories aligned with an account. For goals that are associated with other types of activity plans, the job shares the goals in accordance with the sharing setting of the activity plan.
Offline Mobile Sync
Monetary Caps handles offline monetary cap violations in the mobile differently than on the web.
On the web, when the sales rep attempts to add a participant who has exceeded the monetary cap limits or is at limit, the system blocks the action.
On the mobile, when the sales rep attempts the same action while offline, the system doesn’t block the action. The participant gets added to the other event successfully, but a related Managed Event Participant Discrepancy record is created. When the mobile syncs with the web, the data is shared with the main system.
Monetary Cap Setup
Set up the records and configurations required to activate monetary caps, including activity plans, provider activity goals, measure types with block and warn criteria, and expense types.
Prerequisites
- In the org-level admin console settings for event management, configure the Concluded Event Status field to denote the final value of the status. This setting is used by provider activity goal measure to confirm that the event is over and to calculate the actual expenses for each participant.
- Create a territory in the territory hierarchy. Add a user (sales rep) to the territory, and assign an account, representing the participant, to the territory. For more information, see Set Up Sales Territories for Life Sciences Cloud
- Create an expense type. Make sure the Expense Availability Type is Managed Event, and the start and end dates of the expense type falls within the time period of the activity plan. Select the Included in Cap checkbox. For more information, see Expense Management.
Setup Tasks (Admin)
- Create an activity plan of type Event Management Limit, with a defined time period. The plan should be active.
- Create a provider activity goal for an account added to the territory model. Associate the goal with the activity plan.
- Create provider activity measure types for block (Error) and warning (Warn) scenarios.
This represents the conditions that need to be checked while calculating monetary caps.
- For the block scenario, configure the provider activity measure type by running the
following
code:
ProviderActivityMeasureType pamt = new ProviderActivityMeasureType( DeveloperName = 'PAMTMonetaryCaps', MasterLabel = 'PAMTMonetaryCaps', Category = 'MonetaryCapLimit', IsActive = true, ActivityObject = 'ExpenseParticipant', Criteria = '{"contextCondition":{"conditions":[{"field":"MngEvent.Status","operator":"In","value":"Draft;Completed"}]},"utilizationTypes":{"estimated":{"conditions":[{"field":"MngEvent.Status","operator":"In","value":"Draft;Completed"}]},"committed":{"conditions":[{"field":"MngEvent.Status","operator":"In","value":"Draft;Completed"}]},"actual":{"conditions":[{"field":"MngEvent.Status","operator":"In","value":"Draft;Completed"}]}}}', AlertType = 'Warning' ); insert pamt; - Similarly, create metadata configurations for the warn scenario, with the same details and JSON structure. Select the alert type as Warn.
- For the block scenario, configure the provider activity measure type by running the
following
code:
- Create provider activity goal measures, associated with the provider activity goal, of type Event Management Limit. Add the provider activity measure type created for the monetary cap block scenario.
Setup Tasks (Sales Rep)
For monetary caps to work, the sales rep must set up the basic event management records.
- Create a managed event. Make sure the start date and end date of the managed event falls within the activity plan’s time period.
- Create a managed event participant for the account aligned to the territory.
- Create an expense, and add the managed event and related expense type you created.
Create a Provider Activity Goal Limit
Create the provider activity goal limit, associated with the goal measure. Set the monetary limit that is used by the account across all the events an account is associated with.
Required Editions
| User Permissions Needed | |
|---|---|
| To configure provider activity goal limits: | Life Science Commercial Admin permission set |
The system allows users to record actual expenses that surpass the monetary limit set in the provider activity goal with a Managed Event Participant Discrepancy record created as a warning.
If the provider activity measure type’s Alert Type field is set to Error, the system blocks the participant from being added to another event if their monetary limit is already at cap or has been exceeded.
If the provider activity measure type’s Alert Type field is set to Warn, the system allows the participant to be added to another event even if their monetary limit is already at cap or has been exceeded.
- From the App Launcher, find and select Provider Activity Goal Limits.
- Click New.
-
For Provider Activity Measure Type, select the monetary cap measure type.
Choose the provider activity measure type you created for the block or the warn scenario.
- Select the provider activity goal.
- Enter an amount as the monetary limit. This amount is used by the account across all events.
- Save your changes.
Create an Expense Participant
To help users track expense caps, associate an expense with a participant.
Required Editions
| User Permissions Needed | |
|---|---|
| To create an expense participant: | Event Management permission set |
- From the App Launcher, find and select Expense Participants.
- Add a name for the record.
-
Select an Expense record.
This field captures the total actual expense spent on a particular category.
- For Participant, first select Managed Event Participant and then select the corresponding participant record for whom you’re creating the expense.
- Enter the actual expense incurred for the participant.
- Save your changes.
Activity Plan Record Sharing Rules
Learn more about how activity plans are shared with users, such as the event organizer.
Activity Plan Record Sharing Rules
By default, activity plans and provider activity goals are not shared with non-admin users, like sales reps. To share these records with sales reps, run the Share Provider Activity Goals Based on Activity Plan Type job. The system creates Provider Activity Goal Share records and Activity Plan Share records of Life Sciences Commercial Auto Share type, and shares them with the territories aligned to the participant account.
Prerequisite
Before you run the Share Provider Activity Goals Based on Activity Plan Type job, change the provider activity goal and activity plan sharing settings from Controlled by Parent to Private. You can find the sharing settings in Setup.
How Sharing Works
If activity plans already exist, changing the sharing settings from Parent Controlled to Private also changes the sharing access of the associated provider activity goals, goal measure, and goal limits. To ensure that access is not lost, the batch job shares the activity plans, provider activity goals and associated records based on activity plan type.
If the activity plan type is Event Management Limit, the batch job shares provider activity goals and activity plans with the territories aligned with the account.
If the activity plan type is anything other than Event Management Limit, the batch job shares provider activity goals, and associated goal measures and goal limits, based on the parent activity plan shares.
When provider activity goals are shared, all associated activity plan objects such as provider activity goal measure, provider activity goal limit, are shared accordingly.
How Sharing Works for Manual Shares
Additionally, to ensure that provider activity goals inherit the sharing settings of existing activity plans that were shared manually with users, turn on the Include Records of All Sharing Types in Workflows toggle in Life Sciences for Customer Engagement Setup.
When enabled, this setting considers all sharing types, including manual shares, for all Life Sciences processes. When turned off, Life Sciences workflows only consider the Life Sciences Commercial Auto Share sharing type.
When the Share Provider Activity Goals Based on Activity Plan Type batch job is run after the Include Records of All Sharing Types in Workflows toggle is turned on, the batch job replicates all sharing types, including manual shares, in the provider activity goal sharing settings.
When the toggle is turned off, the batch job only replicates Life Sciences Commercial Auto Share sharing type settings for provider activity goal sharing settings. For more information, see Get Your Org Ready for the Customer Engagement Managed Package.
Monetary Cap Account Merge
Find out about how Event Management uses the Account Merge functionality to calculate monetary limits for participants with overlapping cap data.
The Account Merge functionality uses a two-phase consolidation process to merge the winning account and losing accounts that have Provider Activity Goal Measure records for the same activity plan. For more details, see Account Merge.
In phase one, the Account Merge functionality merges the goal measures for both accounts. Goal measures should be of category Monetary Cap Limit and should be associated with the same activity plan of type Event Management Limit.
The impact of the merge is as follows.
- The losing account’s goal measure is deleted.
- The winning account’s total expense amount is a summation of the expense amounts from the winning and losing accounts.
- The cap data which is stored as JSON in ProviderActivityGoalMeasure.AdditionalInformation now contains expense details from both events.
- The losing account’s participants are still linked to its account but expenses are consolidated into winner’s caps.
In phase two, if the accounts have expenses in the same currency, Account Merge directly sums the estimated, committed, and actual expenses.
If the accounts have different currencies, Account Merge fetches the historical exchange rate for the losing participant account’s expense and converts it to the winning account’s currency, and updates the winner’s total expenses.
The impact of the merge is as follows.
- The losing account’s expenses are converted to the winning account’s currency using the historical transaction rate.
- The winning account’s total expense amount is a summation of the expense amounts from the winning and losing accounts, and includes the converted amount.
- The cap data, which is stored in Provider Activity Goal Measure's Additional Information field, also contains the conversion rates for the audit trail.
