-
Notifications
You must be signed in to change notification settings - Fork 1
Home
The Rewards Building Block (Rewards BB) is the service responsible for managing reward transactions and inventory in the Rokwire ecosystem. This Building Block is designed to support arbitrary reward types and several granting and redemption flows.
API level documentation for this Building Block can be accessed by visiting https://api.rokwire.illinois.edu/rewards/doc/ui/. This documentation conforms to the OpenAPI 3.0 standard. For the raw YAML documentation, you can visit https://api.rokwire.illinois.edu/rewards/doc.
This Wiki provides an overview of the functionality included in the Rewards Building Block. It includes the following sections:
The lifecycle of a reward within the Rewards BB is broken into the following steps.
A new supply of a Reward Type becomes available and a new Inventory is created.
A user performs an action within one of the clients that earns them a given reward. The Building Block responsible for tracking user progress towards this reward sends a request to the /int/reward endpoint to grant the user the reward for the specified Operation.
Once the last inventory of the requested Reward Type is depleted, grants will fail until a new Inventory becomes available. If the Grant Depleted flag is specified on an inventories for this Reward Type, then grants will continue to succeed.
A user would like to claim (redeem) the rewards that they have previously been granted. They send a request to the POST /user/claims endpoint to claim some specified quantity of the rewards available in their balance. This should initiate the Redemption process for the specified Reward Type to ensure that the redeemed rewards are delivered to the user.
Once the last inventory of the requested Reward Type is depleted, claims will fail until a new Inventory becomes available. If the Claim Depleted flag is specified on an inventories for this Reward Type, then claims will continue to succeed.
Reward Types are the fundamental units in the Rewards BB. Every reward that is granted must first have an associated Reward Type defined to be referenced in Inventories and Transaction Histories. For example, if free t-shirts are to be granted as a reward for participating in a student survey, the first step would be to create a tshirt reward type using the POST /admin/types endpoint.
Reward Types contain the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | b1e7dcf3-4829-4d03-921f-6504562864cd |
| Organization ID | org_id |
string | true | The unique identifier of the Organization with which the inventory is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| Reward Type | reward_type |
string | true | A unique, human-readable identifier for the reward type | tshirt |
| DisplayName | display_name |
string | true | A name to be displayed to users that describes the reward type | T-Shirt |
| Active | active |
bool | true | A flag indicating whether or not this reward type is currently active and grantable | false |
| Description | description |
string | true | A short description of the reward type. This will be visible to users. | T-shirts with the University logo |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
The supply of Reward Types are managed and tracked within Inventories. Once a Reward Type has been defined, an Inventory record must be created to define the available quantity of this reward using the POST /admin/inventories. These Inventories also contain configurations for the behavior of the Inventory record. As users are granted and claim these rewards, this record will be automatically updated to reflect the changes.
Inventory records contain the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | 951ce5d6-076a-4185-84e4-2625925440f1 |
| Organization ID | org_id |
string | true | The unique identifier of the Organization with which the inventory is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| Reward Type | reward_type |
string | true | The Reward Type associated with this inventory record | tshirt |
| In Stock | in_stock |
bool | true | A flag indicating whether or not this record represents inventory that is currently in stock | true |
| Amount Total | amount_total |
int | true | The amount of the specified Reward Type that is available in this inventory to start out | 100 |
| Amount Granted | amount_granted |
int | true | The amount of rewards that have been granted from this inventory | 10 |
| Amount Claimed | amount_claimed |
int | true | The amount of rewards that have been claimed from this inventory | 5 |
| Grant Depleted | grant_depleted |
bool | true | A flag indicating whether or not rewards can be granted from this inventory after it has been depleted | true |
| Claim Depleted | claim_depleted |
bool | true | A flag indicating whether or not rewards can be claimed from this inventory after it has been depleted | false |
| Description | description |
string | true | A short description of the inventory | Initial stock of t-shirts based on attendance estimates |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
Before rewards can be granted, Operations must be created to define the quantity and type of reward to be granted for specific user actions. Each Operation is associated with a specific service (eg. Building Block) that is responsible for tracking user progress towards that action. For example, the Groups Building Block may reward a user with one t-shirt for making 10 posts.
Operations contain the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | 52338e08-750e-496c-91f1-76b110d0e725 |
| Organization ID | org_id |
string | true | The unique identifier of the Organization with which the inventory is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| Reward Type | reward_type |
string | true | The Reward Type associated with this inventory record | tshirt |
| Code | code |
string | true | A unique, human-readable identifier for the operation | 10_posts |
| Building Block | building_block |
string | true | The Service ID of the service that is responsible for this reward. Only this service may use this operation. | groups |
| Amount | amount |
int | true | The amount of the specified Reward Type to be granted when this operation is completed | 1 |
| Description | description |
string | true | A short description of the operation. This will be visible to users. | Make 10 posts in a group |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
Once a reward has been granted, it is entered into the user's Reward History.
A Reward History entry includes the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | 52338e08-750e-496c-91f1-76b110d0e725 |
| Organization ID | org_id |
string | true | The unique identifier of the Organization with which the inventory is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| User ID | user_id |
string | true | The Account ID of the user who was granted the reward | cf8a2cc9-48cd-43b3-8003-e6f21c756db2 |
| Reward Type | reward_type |
string | true | The Reward Type associated with this inventory record | tshirt |
| Code | code |
string | true | A unique, human-readable identifier for the operation | 10_posts |
| Building Block | building_block |
string | true | The Service ID of the service that is responsible for this reward. Only this service may use this operation. | groups |
| Amount | amount |
int | true | The amount of the specified Reward Type to be granted when this operation is completed | 1 |
| Description | description |
string | true | A short description of the operation. This will be visible to users. | Make 10 posts in a group |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
The redemption process involves both internal and external components. Internally, redemptions result in the creation of a Claim record. Some external integration may also be necessary for the user to receive their reward.
Claims record that a given user has claimed some amount of a specified Reward Type.
Claim records contain the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| ID | id |
string | true | The unique identifier generated by the system for this item. | 52338e08-750e-496c-91f1-76b110d0e725 |
| Organization ID | org_id |
string | true | The unique identifier of the Organization with which the inventory is associated. | fc6ab5f8-84ef-414b-b979-c1c7611a4c43 |
| User ID | user_id |
string | true | The Account ID of the user who was granted the reward | cf8a2cc9-48cd-43b3-8003-e6f21c756db2 |
| Items | items |
list(ClaimItem) | true | A list of Claim Items included in this claim | |
| Status | status |
string | true | The current status of this claim | ?? |
| Description | description |
string | true | A short description of the operation. This will be visible to users. | Make 10 posts in a group |
| Date Created | date_created |
DateTime | true | The time that this item was originally created | 2022-06-01T12:21:06Z |
| Date Updated | date_updated |
DateTime | true | The time that this item was last updated | 2022-06-06T21:23:19Z |
A Claim Item represents one component of a Claim.
Claim Items include the following data:
| Name | Key | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Reward Type | reward_type |
string | true | The Reward Type associated with this inventory record | tshirt |
| Inventory ID | inventory_id |
string | true | The unique identifier of the Inventory from which the reward was claimed | 951ce5d6-076a-4185-84e4-2625925440f1 |
| Amount | amount |
int | true | The amount of the specified Reward Type claimed | 1 |
In order for the user to actually receive the reward, some integration may be necessary to initiate a delivery. For example, if the rewards are digital gift cards or currencies, an integration with an external system will be needed to perform a transfer or create a gift card code. If the rewards are physical, then some process may need to be started to have them shipped to the user.
Each user maintains a balance of each Reward Type. The balance is the sum of all granted rewards in the user's History minus all of the rewards that the user has Redeemed.