NOTE: This is early documentation for the scheduling system and the documentation will be further extended over time with additional examples and more details

Advanced Scheduling

The ThrillPots system provides a relatively sophisticated sub-system which allows you to create schedules for your jackpot products.

It is important to understand what a schedule is in the context of ThrillPots.

At its core, a schedule is always bound to a Jackpot Instance. A schedule can be as simple as defining the date and time that a jackpot starts at, or defining an end date and time for jackpot.

Here are some interesting use cases that can be solved with schedules as well:

Happy Hour Jackpot: Creating a jackpot that only accepts contributions during 17:00 and 18:00
Promotional Jackpots: Creating a jackpot that only accepts contributions at peak times of site activity or to encourage players during low activity times
Weekend Jackpots: Creating a jackpot that is only available on weekends

Schedules become even more powerful when used together with Raffle Jackpots. Raffle Jackpots are jackpots that resolve at the end of a predefined period of time. While players participate in the Raffle Jackpot by way of contribution (as with any other jackpot), raffle jackpots issue tickets to players based on either their Contribution or the base wager that they make into games.

Recurrence Rulesets

All the rules for the scheduling system revolve around "recurrence rules". Currently, recurrence rules are implemented for "Daily" and "Weekly" rulesets.

Daily rules

Daily rules define a set of hours within which the jackpot is available in. Traditionally, jackpot contributions are allowed during all hours of the day, but lets imagine that you wanted to create a jackpot that was only available during your site's "Happy Hour" which was between the hours of 7pm to 9pm UTC.

For such a rule to exist, you would only need to define a Daily recurrence rule which stipulated that the hours of 19:00 to 21:00 UTC were valid.

Weekly rules

Taking the example from above, lets imagine that we wanted to further constrain the available days of the raffle to be from Monday to Friday (no weekend contributions allowed!). In this case, we would create a "Weekly" ruleset which define the following days as being valid: Monday through to Friday.

As a last minute change, business might want to allow contributions to happen on a Saturday, but only between 08:00 UTC to 20:00 UTC. To allow this specificity of ruleset, we can apply an additional override for Saturday for those specific hours at the Weekly schedule level.

Technical Example

For a technical example of what a complete schedule as described above would look like, the following JSON structure accurately describes the ruleset. For arguments sake, we will define the schedule to start on the 1st of January 2024 UTC, with no end to the schedule.

To summarise, we will be creating a schedule that:

Allows contributions to occur Monday, Tuesday, Wednesday, Thursday, Friday and Saturday
From Monday to Friday, contributions will be allowed between 19:00:00 UTC and 21:00:00 UTC
On Saturdays, contributions will be allowed between 08:00:00 UTC and 20:00:00 UTC

{
	"timestamp_start": 1704067200000,
	// No `timestamp_end` is specified since the schedule has no end
	"recurrence_rules": [
		{
			"frequency": {
				"Daily": {
					"hours": [
						[
							{ "hour": 19, "minute": 0, "sec": 0 }.
							{ "hour": 21, "minute": 0, "sec": 0 }
						]
					]
				}
			},
			"interval": 1, // 1 means "every day". 2 would mean "every second day"
		},
		{
			"frequency": {
				"Weekly": {
					"days": [
						["Mon", null].
						["Tue", null],
						["Wed", null],
						["Thu", null],
						["Fri", null],
						["Sat", {
							"Daily": {
								"hours": [
									[
										{ "hour": 8, "minute": 0, "sec": 0 },
										{ "hour": 20, "minute": 0, "sec": 0 }
									]
								]
							}
						}]
					]
				}
			}
		}
	]
}

As can be seen from this example, when defining the Weekly rule, each day of validity needs to be specified, along with any overrides to the underlying Daily rules that may exist.

Order of Precendence

It is important to note that any hourly overrides present in the Weekly ruleset will take precedence over those specified in the Daily rules.

How Scheduled Jackpots work

When a schedule is applied to a normal Jackpot Instance, the system performs some rudimentary initial checks (making sure that when the jackpot is created with a schedule in the future, that the status is correctly set to Pending).

Once the Jackpot Instance is Active, the applied schedule defines the periods of time during which contributions will be accepted by the Jackpot Instance. When the schedule is not accepting contributions, the Jackpot Instance will continue to be Active (this behaviour may change in the future).

How Scheduled Raffles work

When instantiating Raffle Jackpots, a schedule must be provided during instantiation time

The reason for this is due to the fact that raffles are fundamentally time-based entities with at least a start time and duration-per-raffle.

Raffles have an explicit duration which is defined as part of the Raffle Rules. Durations can be defined in units of Seconds, Minutes, Hours, Days or Weeks.

Raffles that have a schedule that is longer than a raffles duration are considered "recurring raffles" while raffles that have a schedule equal to their duration are considered "once-off raffles".

Lets examime a few examples to explore this concept:

Once off Raffles

Lets imagine a scenario where an operator wants to run a once-off raffle for the Festive season (Xmas) period which start from 00:00:00 UTC on the 1st of December 2024 and the raffle resolves (pays out) at 09:00:00 UTC on the 25th of December 2024.

Additional requirements for the raffle are that the raffle should only accept contributions between the hours of 8am CET until the end of each day.

In order to create a schedule for this type of raffle, we need to create rules that specify the hourly restrictions as well as the start and end of the raffle.

Example

{
	// Sunday, 1 December 2024 00:00:00
	"timestamp_start": 1733011200000,
	// Wednesday, 25 December 2024 09:00:00
	"timestamp_end": 1735117200000
	"recurrence_rules": [
		{
			"frequency": {
				"Daily": {
					"hours": [
						[
							{ "hour": 8, "minute": 0, "sec": 0 }.
							{ "hour": 23, "minute": 59, "sec": 59 }
						]
					]
				}
			},
			"interval": 1,
		}
	]
}

As can be seen in the example, the timestamp_start and timestamp_end have been set to the period of the Festive Season (December 1st, 2024 to December 25th 2024 respectively) and the hours of availability are set from 08:00:00 UTC to 23:59:59 UTC.

Since the jackpot is available on all days through the period, there is no need to define the Weekly ruleset.

In addition to the schedule, the raffle will also need to be configured to run for the duration of the schedule. In this case, the duration will be 24 days and 9 hours.

NOTE In general, you as an operator do not need to worry about the duration configuration as this is configured as part of the Jackpot template by the ThrillTech Jackpot Model design team and not something you as an operator need to worry about.

Daily Raffles

In this example, we will be configuring a Raffle jackpot that is available on all days of the week and will resolve (pay prizes to players) at 10pm UTC (22:00:00 UTC) each day. The raffle will start at 00:00:00 of each day and end when it resolves daily.

Example:

In this example, the raffle started on August 1st, 2024 at 00:00:00 UTC:

{
	// Thursday, 1 August 2024 00:00:00
	"timestamp_start": 1722470400000,
	"recurrence_rules": [
		{
			"frequency": {
				"Daily": {
					"hours": [
						[
							{ "hour": 0, "minute": 0, "sec": 0 }.
							{ "hour": 22, "minute": 0, "sec": 0 }
						]
					]
				}
			},
			"interval": 1,
		}
	]
}

In addition to the schedule, the raffle's duration will be defined to last 22 hours.

ThrillTech Technology & Integration Guide (SaaS)