Eligibility Rule Examples

Eligibility rules define requirements and exclusions that specify which subscribers, groups, and devices are eligible to purchase certain catalog items. A catalog is a set of requires and excludes eligibility rules evaluated against the catalog items. The following examples illustrate catalog and catalog item eligibility rule usage.

An eligibility rule is a rule on an attribute or a feature. Requires rules are evaluated using the AND condition, and excludes rules are evaluated using the OR condition. Only rules that apply to the object type of the SubMan API request are evaluated.

For example, if a catalog item contains eligibility rules with ObjectType=subscriber and ObjectType=group:

When a Subscriber API request is made, rules with ObjectType=subscriber are evaluated.
When a Group API request is made, rules with ObjectType=group are evaluated.
When a Device API request is made, there is no applicable rule, so rule evaluation is not performed.

When defining eligibility rules, you must have separate rules with the correct ObjectType:

For catalog item requires and excludes rules, the eligibility rules must have ObjectType=subscriber, ObjectType=group, or ObjectType=device.
For catalog requires and excludes rules, the eligibility rules must have ObjectType=catalog_item.

Catalog Item Eligibility Rules

Consider the following catalog items. The eligibility rules in a catalog item have ObjectType=subscriber, group, or device:


Catalog Item	Eligibility Features	Require Rules
ItemGold	Name=Gold
ItemSilver	Name=Silver Name=SilverEvening
ItemBronze	Name=Bronze
ItemMorning	Name=Morning	ObjectType=subscriber, EntityType=feature,Name=Gold
ItemAfternoon	Name=Afternoon	ObjectType=subscriber, EntityType=feature, Name=Gold
ItemEvening	Name=Evening Name=SilverEvening	ObjectType=subscriber, EntityType=feature, Name=Gold

ItemMorning, ItemAfternoon, and ItemEvening require the subscriber to have the feature Gold.
Because the Require rules are processed using the AND condition, to query features Silver or Evening, you must define an eligibility feature SilverEvening and assign this feature to the catalog items that have the feature Silver or Evening. In this example, ItemSilver and ItemEvening are assigned the feature SilverEvening.

To retrieve the list of catalog items that have a particular feature, define a catalog with the appropriate eligibility rules. The rules in a catalog should have ObjectType=catalog_item.


Catalog	Require Rules
CatalogSilver	ObjectType=catalog_item, EntityType=feature, Name=Silver
CatalogSilverEvening	ObjectType=catalog_item, EntityType=feature, Name=SilverEvening

Catalog Query and List of Catalog Items

This pricing API returns information about a catalog and the list of catalog items that satisfy the eligibility rules defined in the catalog:

SubMan API: MtxRequestPricingQueryCatalog
REST API: /pricing/Catalog/{SearchTerm:.+}


Specified Catalog	CatalogItemList in PricingQueryCatalog Response
CatalogSilver	ItemSilver
CatalogSilverEvening	ItemSilver ItemEvening

This pricing API does not have the EligibilityFilter parameter; it only checks ObjectType=catalog_item rules and returns the catalog items that satisfy the rules.

The following APIs are for a specific subscriber, group, or device. The EligibilityFilter Boolean parameter indicates whether only the eligibility items are returned:

EligibilityFilter=true means to return only the eligible catalog items. This is the default.
EligibilityFilter=false means to return all catalog items and set EligibilityResult=true for the eligible catalog items and EligibilityResult=false for the ineligible catalog items with the reason in EligibilityResultList.

The subscriber APIs check ObjectType=subscriber rules.

The group APIs check ObjectType=group rules.

The device APIs check ObjectType=device rules.

Catalog Query on Subscriber

This API returns information of a catalog and the list of eligible catalog items in the catalog for the specified subscriber:

SubMan API: MtxRequestSubscriberQueryCatalog
REST API: /subscription/{SearchTerm:.}/catalog/{CatalogSearchTerm:.}

In this example:

CatalogSilver includes ItemSilver.
CatalogSilverEvening include ItemSilver and ItemEvening.

If Subscriber has not purchased ItemGold, the query response of MtxRequestSubscriberQueryCatalog will be as follows:


EligibilityFilter Parameter	Specified Catalog	CatalogItemList in SubscriberQueryCatalog Response
true	CatalogSilver	ItemSilver
true	CatalogSilverEvening	ItemSilver
false	CatalogSilver	ItemSilver, EligibilityResult=true
false	CatalogSilverEvening	ItemSilver, EligibilityResult=true ItemEvening, EligibilityResult=false,EligibilityResultList="Gold" rule

If Subscriber has purchased ItemGold, the query response will be as follows:


EligibilityFilter Parameter	Specified Catalog	CatalogItemList in SubscriberQueryCatalog Response
true	CatalogSilver	ItemSilver
true	CatalogSilverEvening	ItemSilver ItemEvening
false	CatalogSilver	ItemSilver, EligibilityResult=true
false	CatalogSilverEvening	ItemSilver, EligibilityResult=true ItemEvening, EligibilityResult=true

Catalog Item Query on Subscriber

This API iterates all the catalog items and returns the list of eligible catalog items for the specified subscriber:

SubMan API: MtxRequestSubscriberQueryCatalogItemList
REST API: /subscription/{SearchTerm:.+}/CatalogItem

If Subscriber has not purchased ItemGold, the query response of MtxRequestSubscriberQueryCatalogItemList will be as follows:


EligibilityFilter Parameter	CatalogItemList in SubscriberQueryCatalogItemList Response
true	ItemGold ItemSilver ItemBronze
false	ItemGold, EligibilityResult=true ItemSilver, EligibilityResult=true ItemBronze, EligibilityResult=true ItemMorning, EligibilityResult=false, EligibilityResultList="Gold" rule ItemAfternoon, EligibilityResult=false, EligibilityResultList="Gold" rule ItemEvening, EligibilityResult=false, EligibilityResultList="Gold" rule

If Subscriber has purchased ItemGold, the query response will be as follows:


EligibilityFilter Parameter	CatalogItemList in SubscriberQueryCatalog Response
true	ItemGold ItemSilver ItemBronze ItemMorning ItemAfternoon ItemEvening
false	ItemGold, EligibilityResult=true ItemSilver, EligibilityResult=true ItemBronze, EligibilityResult=true ItemMorning, EligibilityResult=true ItemAfternoon, EligibilityResult=true ItemEvening, EligibilityResult=true

For information about querying catalog items based on eligibility, see the discussion about eligibility rules REST APIs in MATRIXX Subscriber Management API. For information about querying information about pricing catalogs for specified devices, groups, and subscriptions, see the discussion about catalog REST APIs in MATRIXX Subscriber Management API.