SQS technical overview

The SQS facilitates sharing data, credit, or time between subscribers in what is called quota sharing. Donors are subscribers who share their quota by making a donation to another subscriber (the recipient). Recurring donations can also be configured and when the plan itself renews, the configured recurring donation is automatically made. For more on how to do this, check out creating a recurring donation.

Quota is typically represented in data volume (bytes). However, it can sometimes be configured to be shared as credit or time via setting the option in the unitMeteringType field of the plan definition for the shareable plan. This information is received by the SQS as either a % or amount from the subscriber. See Plan definition type descriptions for more details on the unitMeteringType field.

The SQS standard flow

sqs overview graphic

The standard sharing quota flow goes as follows:

  1. A client sends a donation request to the SQS.

  2. This triggers the SQS to ask the SPCM for the donor plan information.

  3. Quota is deducted from the donor plan.

  4. Quota is then added to all recipients as per the request.

When the quota is shared, the recipient receives a notification.

For recurring donations, (5) when a successful plan renewal occurs in the SPCM, (6) a recurring plan event is enabled by rabbitmq and consumed by the SQS (which checks to make sure there is a recurring donation configured for the plan). (7) If so, it performs the donation as in the standard flow.

What happens if sharing fails?

  • If adding quota for any recipient fails, the deduction from the donor’s plan (for that recipient) is rolled back by the amount allocated in the request and does not impact the other recipients.

    Example

    If 3 recipients are defined to receive a quota of 10,20,and 30 MB respectively and the second recipient (20mb) fails, only that 20mb is rolled back. This might happen if a recipient was deleted from the system or a maximum plan limit has been reached.

  • A donation to a recipient can fail if the maximum recipient limit is reached.

    Example

    If a donor tries to share a plan with 3 recipients, but the plan definition has a maximum recipient limit set to 2, the donation for the third recipient will fail without impacting the first two recipients.


Plan definition type descriptions

Field Type Description

id

integer

The unique identifier for the plan. This is assigned by the server upon creating a plan definition.

mandatory when updating a plan definition.

name

string (255)

The name of the plan definition.

mandatory when creating a plan definition.

unitAmount

string (255)

This tells you the number of units a plan definition provides. The unit type is defined in unitMeteringType.

mandatory when creating a plan definition.

unitMeteringType

enum

Defines the unit type. This can be time (seconds), volume (bytes), or credits (currency’s lowest denomination; for example a cent so 100 units equals $1).

mandatory when creating a plan definition.

cost

integer

The cost or purchasing the plan. Like unitMeteringType, the cost is in the lowest denomination of the currency (i.e., 1 cent so 100 units equals $1).

mandatory when creating a plan definition.

validityPeriod.validityPeriod

string (255)

A formatted string that displays for how long a plan definition exists. An example is 2days3hours2minutes.

mandatory when creating a plan definition.

validityPeriod.absoluteExpiryTime

string

Denotes the hour, minute, and second at which the plan will expire or renew.

NOTE: If not set, the plan will expire or renew relative to the purchase timestamp (timestamp + validity period). This format is hh:mm:ss.

precedence

integer

The precedence of the plan over other plans purchased by the subscriber where 0 is the highest precedence.

mandatory when creating a plan definition.

recurring

boolean

Denotes whether a plan is recurring or not where true is recurring and false is not.

mandatory when creating a plan definition.

core

boolean

Indicates if this plan is the core plan for the subscriber where true is the core plan and false is not.

mandatory when creating a plan definition.

summary

string (2048 char)

A brief summary describing the plan.

maxDeactivationCount

integer

The amount of times a plan definition can be deactivated.

maxOccurenceCount

integer

The maximum number of times a recurring plan can recur.

recycleRollOverLimit

integer

The maximum amount of unused data usage that can be carried forward when a plan is renewed.

mandatory when creating a plan definition.

accumulationPermitted

boolean

Indicates if accumulation is permitted where true is permitted and false is not.

mandatory when creating a plan definition.

dpsEnabled

boolean

Indicates whether DPS is enabled where true means DPS is enabled and false means it is not.

mandatory when creating a plan definition.

activateOnPurchase

boolean

Indicates if a plan is activated upon purchase where true means the plan is activated on purchase and false means it is not.

mandatory when creating a plan definition.

shared

boolean

Indicates if a plan is shared where true means it is shared and false means it is not shared.

mandatory when creating a plan definition.

version

integer

Denotes the version of the plan

mandatory when creating a plan definition.

shareQuotaMaxRecipients

integer

Specifies the maximum number of recipients with whom quota can be shared.

This is an optional field.

grantedAmount

integer

The chunk size that is granted to a data session. The session reports usage after using the granted amount.

The grantedAmount can be credit, volume, or time. This is determined by what is set in the unitMeteringType.