FieloPLT.IncentivesAPI Class

Generally used for the Incentives component, the FieloPLT.IncentivesAPI Class includes two methods.

Get Incentives (getIncentives)

Map<String, List<IncentivesWrapper>> FieloPLT.IncentivesAPI.getIncentives(String type, Id memberId, Set<Id> incentivesId, String setName, Map<String, Set<String>> fieldsMap, Map<String, String> filterMap, Map<String,String> orderByMap, Integer quantity, Integer offset, Boolean translate, Boolean calculateMissionsProgress, Boolean calculateElibilityCriterias)

Instead of using the APIs that are specific for Challenges and Promotions, this method will allow you to retrieve any data that you might need from any Incentive that a particular member is participating in. You can use this is order to display to the members all the information that they might need to know abou the incentive in which they are participating, such as the challenge mission's goal, for example.

The advantage of using getIncentives, is that you would need only one API instead of two. It can also provide information regarding the member's progress in a Challenge Mission and their eligibility in it, which is related to the criteria that the member needs to accomplish in order to be able to participate in the Incentive - the method's return specifies if the member has already accomplished the criteria or not.

Take a look at a step by step guide on how to use this method.

Parameters

Check an example of how the API can be used below and a definition of its parameters right after:

//Example for Challenges
String  type = 'challenge';
//Get member Id
Id memberId = [SELECT Id FROM FieloPLT__Member__c LIMIT 1].Id;
//Get challenges Id
Map<Id, FieloPLT__Challenge__c> challenges = new Map<Id, FieloPLT__Challenge__c>([SELECT Id FROM FieloPLT__Challenge__c]);
Set<Id> incentivesId = new Set<Id>(challenges.keySet());
String setName = 'MyChallenges';
// Fieldset for each Incentive and related Objects
Map<String, Set<String>> fieldsMap = new Map<String, Set<String>>();
fieldsMap.put('challenge', new Set<String>{'Id, Name'});
fieldsMap.put('rank', new Set<String>{'Id, Name'});
fieldsMap.put('chreward',new Set<String>{'Id, Name'});
fieldsMap.put('missionmember', new Set<String>{'Id, Name'});
fieldsMap.put('chmember', new Set<String>{'Id, Name'});
fieldsMap.put('transaction', new Set<String>{'Id, Name'});
// Filters for each Incentive
Map<String, String> filterMap = new Map<String, String>{'challenge' => '[{"field":"Name","value":"challenge with progress","operator":"eq"}]'};
Map<String, String> orderByMap = new Map<String, String>{'orderByChallenge' => 'Name Asc'};
Integer quantity = 50;
Integer offset = 0;
Boolean translate = true;
Boolean calculateMissionsProgress = true;
Boolean calculateElibilityCriterias = false;
//Get Incentives
List<FieloPLT.IncentivesAPI.IncentiveWrapper> incentivesInfo = FieloPLT.IncentivesAPI.getIncentives(type, memberId, incentivesId, setName, fieldsMap, filterMap, orderByMap, quantity, offset, translate, calculateMissionsProgress, calculateElibilityCriterias);

//Example for Promotion
String  type = 'promotion';
//Get member Id
Id memberId = [SELECT Id FROM FieloPLT__Member__c LIMIT 1].Id;
//Get promotions Id
Map<Id, FieloPLT__Promotion__c> promotions = new Map<Id, FieloPLT__Promotion__c>([SELECT Id FROM FieloPLT__Promotion__c]);
Set<Id> incentivesId = new Set<Id>(promotions.keySet());

String setName = 'Active';
// Fieldset for each Incentive and related Objects
Map<String, Set<String>> fieldsMap = new Map<String, Set<String>>();
fieldsMap.put('promotion', new Set<String>{'Id, Name'});
fieldsMap.put('rule', new Set<String>{'Id, Name'});
// Filters for each Incentive
Map<String, String> filterMap = new Map<String, String>();
Map<String, String> orderByMap = new Map<String, String>{'orderByPromotion' => 'Name Asc'};
Integer quantity = 50;
Integer offset = 0;
Boolean translate = true;
Boolean calculateMissionsProgress = false;
Boolean calculateElibilityCriterias = true;
//Get Incentives
List<FieloPLT.IncentivesAPI.IncentiveWrapper> incentivesInfo = FieloPLT.IncentivesAPI.getIncentives(type, memberId, incentivesId, setName, fieldsMap, filterMap, orderByMap, quantity, offset, translate, calculateMissionsProgress, calculateElibilityCriterias);

Parameter	Type	Description	Required
type (Required)	String	Should be either promotion or challenge. It cannot be `null`.	Yes
memberId	Id	A specific member's ID.	Yes
incentivesId	Set<Id>	A set of Incentive IDs to return. If null or empty, returns all Incentives that the member is participating in.	No
setName	String	Incentive status to filter values in the response (Values may be: MyChallenges, MyPromotions, Apply, Not Apply, All Available, Active, Open, Completed, Lost, Not Applicable and Apply By Segmentation). These values are case sensitive.	No
fieldsMap	Map`<String, Set<String>>`	Specifies the fields from the Promotion and Challenge Objects that are going to be returned. The map’s key must be all lowercase.	No
filterMap	Map<String, String>	JSON parameter to filter by an additional WHERE Clause. Divided by the type, e.g. <"promotion", dynamicFilter> When null or empty, no filter is applied. If null, calculateMissionsProgress must be false. It shouldn't be used to filter the incentive by status. The status is defined by the setName.	No
orderByMap	Map<String,String>	Records returned in: an ascending or descending order (orderByChallenge and orderByPromotion), and based on the activity (orderByMemberActivity).	No
quantity	Integer	Number of items to be retrieved. When null, query returns all items.	No
offset	Integer	Number of records from a collection to skip. When null, no records are skipped.	No
translate	Boolean	If this parameter is set to (true), it fetches the available translation and changes the language of the component according to the member’s Salesforce user language. If (false), it’ll return the components in the default language.	No
calculateMissionsProgress	Boolean	Show the member's progress in a Challenge Mission (true), or not (false). E.g. has closed 1 opportunity out of 5. If set to (true) when `type = promotion`, it doesn't work. You will see this information in the return labeled as `progress`.	No
calculateElibilityCriterias	Boolean	When (true), returns the segment criteria that must be accomplished in order to be able to participate in the Incentive, detailing what the member has already accomplished and what they haven't. You will see this information in the return labeled as `ElibilityCriteriasWrapper`.	No

setName

This parameter controls which set of Incentives will be returned (these values are case sensitive):

MyChallenges: It returns all the challenges which the member is participating in (exists challenge member, challenge member status can be any).
MyPromotions: This call will return all Promotions applicable to the member’s segment with status equal to Active, Inactive, Scheduled, Edited and Ended which either the Agreements have been accepted by the member or there is no Agreement at all.
Apply: It returns all incentives that the member can participate in, meaning they are not subscribed yet and the member belongs to the incentive segmentation. The incentive status can be either Active, Edited, or Scheduled, and, if it is a challenge, the subscription must be either Open or Global. It will also return promotions that have an Agreement but the Member hasn't accepted it yet.
Not Apply (for challenges): It returns all challenges where the member cannot participate (doesn’t exist ChallengeMember), meaning they are not subscribed yet and don't belong to the challenge segmentation. The challenge status can be either Active, Edited, or Scheduled and the subscription must be either Open or Global.
Not Apply (for promotions): This call will return Promotions with Segments that are not applicable for the member.
All Available: The aggregation of Apply and Not Apply. It returns all the incentives that the member can and cannot participate in regardless of segmentation. If it is a challenge, it will return only the ones that the Member is not enrolled in. It will also return promotions that have an Agreement but the Member hasn't accepted it yet.
Active: It returns all Active incentives which the member is already participating in. Also returns the ones which the member belongs to the segmentation and - if it is a challenge - the subscription is Global.
Open: It returns all the Active or Edited incentives which the member can participate in, meaning that they belong to the incentive segmentation, and - when it is a challenge - it has the Private or Open (Opt-in) subscription mode.
Completed: Only for challenges. It returns challenges completed by the member, which incentive status is equal to Completed and the challenge member status isAccomplished*.
Lost: It returns all incentives which the member could have participated in, as they belonged to the incentive’s segment, but they didn’t and now the incentive Status is equal to "completed".
Not Applicable: It returns all Active and Edited incentives which the member cannot participate in, as the member doesn't belong to the incentive's segment. It doesn't matter the subscription mode the challenge is using.
Apply By Segmentation: Returns all promotions that match the member's segments (independent of whether the promotions have an agreement or not), all challenges that match the member's segments, and all challenges that the member is already enrolled in.
null: If the parameter is left blank, then the return to the call will be all the incentives.

Return Value

Take a look below at an example of what is returned in the call and a definition of the return values right after:

//RETURN for the challenge example
IncentiveWrapper:[challengeMembers=(FieloPLT__ChallengeMember__c:{FieloPLT__Challenge__c=a0FS000000EIWBBMA5, Id=a0DS000000BoGipMAF, FieloPLT__Member__c=a0dS0000005TC9iIAG, Name=CHM-000000}), elibilityCriteriasMap={}, eligible=true, incentive=FieloPLT__Challenge__c:{FieloPLT__Status__c=Active, FieloPLT__Subscription__c=Open, Id=a0FS000000EIWBBMA5, Name=challenge with progress}, incentiveId=a0FS000000EIWBBMA5, mapChMemberIdListMissionMember={a0DS000000BoGipMAF=(FieloPLT__MissionMember__c:{FieloPLT__ChallengeMember__c=a0DS000000BoGipMAF, Id=a0eS0000006wOaTIAU, FieloPLT__Mission__c=a0fS000000DzEJBIA3, Name=MM-000000, FieloPLT__Counter__c=2, FieloPLT__Summary__c=0.00})}, missions=(FieloPLT__Mission__c:{FieloPLT__Challenge__c=a0FS000000EIWBBMA5, Id=a0fS000000DzEJBIA3, Name=10 events, FieloPLT__Type__c=With Objective, FieloPLT__ObjectiveType__c=Counter, FieloPLT__Operator__c=equals, FieloPLT__ObjectiveValue__c=10.00, FieloPLT__ValueMode__c=Fixed, fieloplt__objectivetype__c_label=Count the number of times the action has been performed., fieloplt__operator__c_label=equals, fieloplt__valuemode__c_label=Fixed}), progress={a0dS0000005TC9iIAG=Progress:[missions={a0fS000000DzEJBIA3=Mission:[ObjectiveType=Counter, objectiveValue=10.00, status=null, type=With Objective, value=2]}]}, rules=null, type=challenge]

//RETURN for the promotion example
IncentiveWrapper:[challengeMembers=null, elibilityCriteriasMap={a10S0000005C8GWIA0=(ElibilityCriteriasWrapper:[applyCriterion=true, currentValue=null, goalValue=null, nameCriterion= Criteria one], ElibilityCriteriasWrapper:[applyCriterion=false, currentValue=0, goalValue=5, nameCriterion=5 redemptions])}, eligible=false, incentive=FieloPLT__Promotion__c:{Id=a0qS0000005IZV0IAO, Name=Promotion 1, FieloPLT__Segment__c=a10S0000005C8GWIA0}, incentiveId=a0qS0000005IZV0IAO, mapChMemberIdListMissionMember=null, missions=null, progress=null, rules=(FieloPLT__Rule__c:{FieloPLT__Promotion__c=a0qS0000005IZV0IAO, Id=a0zS0000008cqIoIAI, Name=Rule1}), type=promotion]
)

Type	Description
List<IncentivesWrapper>	Returns a list of List`<IncentiveWrapper>`, related to the Promotions or Challenges (depending on the `type` defined in the request) that the member is participating in. The wrapper includes extra info, such as the member's eligibility and progress in the incentive.

Exception

Errors can occur when you use the endpoint. See below the exception that you can receive when using the getIncentives:

Type	Description
FieloApiException	Parameter {type} is necessary.* When type is either invalid or empty.

Parameter	Type	Description
challengeMembers	List<ChallengeMember__c>	Specifies information regarding the challenge member associated with the member that is participating in the incentive, such as their ID. If the `type` sent in the request was "promotion", this parameter will be null.
elibilityCriteriasMap	Map`<Id, List<ElibilityCriteriasWrapper>>`	Specifies the mission’s or rule’s criteria. More details below.
eligible	Boolean	Defines if the member has accomplished all the criteria and is eligible to participate in the incentive (true) or if they can’t participate (false).
incentive	sObject	It delivers information regarding the incentive that the member is participating in, such as its name, status and segment.
incentiveId	Id	Specifies the Incentive’s ID.
mapChMemberIdListMissionMember	Map<Id,List<MissionMember__c>>	Map of Challenge Member ids (key) by List of Mission Member (value) for each Incentive of challenge type. If the `type` sent in the request was "promotion", this parameter will be null.
missions	List<Mission__c>	It delivers all of the mission’s information. E.g. its name, ID, objective type, etc. If the `type` sent in the request was "promotion", this parameter will be null.
progress	Map<Id, Progress>	Specifies the mission objective and the member’s progress towards reaching it. If the `type` sent in the request was "promotion", this parameter will be null. The Progress wrapper is explained below.
rules	List<Rule__c>	It delivers all of the rule’s information. E.g. its name, ID and the ID of the promotion it is related to. If the `type` sent in the request was "challenge", this parameter will be null.
type	string	It will be either challenge or promotion, depending on which one was sent in the

Internal Wrappers

Within the return, you will find some wrappers. See more information about them below.

Progress

Progress is a wrapper that details the member's progress in the mission, saying how much of the objective has been reached. It has one attribute, called missions.

Parameter	Type	Description
missions	Map<Id, Mission>	It is a map from mission ID (key) by wrapper mission (value).

Missions

Missions is the wrapper that you will find within the Progress.

Parameter	Type	Description
type	String	It defines the mission’s type: based on a fixed metric (with objective) or compare among members (without objective).
status	String	It defines if the mission’s historical data was already evaluated for all mission members (processed) or not (to be processed). If the “Do you want historical data processed?” is not active for the mission, then `status = null`.
ObjectiveType	String	It specifies the mission’s aggregation: Count the number of times the action has been performed or Sum up the Aggregate Field value over all actions performed.
value	Decimal	It says how much of the mission objective the member has accomplished (related to the objectiveValue).
objectiveValue	Decimal	It details what is the mission objective’s value.

ElibilityCriteriasWrapper

ElibilityCriteriasWrapper is a wrapper within the elibilityCriteriasMap attribute of the return. It brings information regarding the criteria that the member must accomplish in order to be able to participate in an incentive.

Remember that the criteria is defined by the segments used for the incentive.

Parameter	Type	Description
applyCriterion	Boolean	Defines if the member applies to the incentive’s criteria (true) or not (false).
nameCriterion	String	Specifies the criteria’s name, if it has one.
goalValue	String	If the criteria is related to something’s amount or quantity, it is detailed here. E.g. the member needs to have 5 redemptions.
currentValue	String	How much the member actually has (related to the goalValue).

Enroll (enroll)

Map<Id,Map<Id, String>> FieloPLT.IncentivesAPI.enroll(Map<Id, Set<Id>> incentivesIdByMemberId, Boolean partialEnroll)

This method will combine information from agreement and subscription in order to enroll one or more members into one or more Active, Scheduled or Edited (which appears as being active) Incentives. This means that, if the incentive has an agreement related to it, the system will check if the member has already accepted it: if they haven't, the system will accept it for them.

If the incentive that you are going to enroll the member in is a challenge, the enroll will also create a Challenge Member.