Scheduling

Skylark’s Scheduling feature decides on content availability. It can be used both to manage rights and to target specific users.

“Schedules”, objects that decide on the availability of objects associated with them, can either be created by editors or ingested.

Availability is decided on each request, with attributes of the request and of the requester factoring in, namely:

Time of the request
Language of the requester
Locale (typically country) where the request originated
Region to which the request’s origin belongs
Device type from which the request was made (Android app, iOS app on iPhone, iOS app on iPad, web browser, Playstation 4 app …)
Affiliate through which the requester logged in or is associated
Type of the customer, which can be several or none at all, usable for arbitrary grouping of users

Schedules

The values that these attribute can take are fully customizable and modifiable at any time.

In this diagram are:

An article visible only on Android devices for English speakers from Dec 25th
A season visible both on Android devices for English speakers from Dec 25th and also visible in France to anyone at anytime
A set visible in France by anyone at anytime

Additionally, Schedules can be associated to objects as part of its membership of a set. The availability of an object as member of a set is therefore decided both by these schedules and those associated with the object itself.

In this image:

A Brand only available in South Korea
A Set containing the Brand, returning it only when queried by Korean speakers

Use Cases

Make a TV Show only available to mobile devices
Make movies available only to Sky subscribers. Make another batch of movies intersecting with the previous one available only to BBC subscribers. The intersection will be visible by both groups of clients.
Target minority languages speakers: Display a film only in the Basque version of your website
Easily manage complex distribution rights:
Make two schedules managing rights agreed on with distributors:
- Available in France, Great Britain, Portugal for people speaking French and English, visiting on an Android device that connect via Sky, Canal + or MEO from March, 1st 2017 to June, 5th 2017
- Available in the United States and Japan, for people speaking French, English and Japanese, visiting on iPhone in 2018
- Assign them to brands and let Skylark clarify to whom they are available
  Personalise your homepage: only show content available and relevant to the demographic of the current user
Add a Schedule managing rights to Christmas movies: Active worldwide
Create a Schedule targeting users for Christmas: Active in the western world from December 1st to December 31st
Add the Christmas movies to the set managing your homepage, linked as members of the set to the Christmas Schedule
During the month of December, the homepage of the mobile app of users in the western world shows these Christmas movies
A/B testing by dividing the user base into groups and providing them with different content

Technical Description

The Schedule Object

Schedules are a descriptor of availability. They can be linked with a wide range of objects in Skylark. This is called “scheduling an object”, and objects that can be scheduled are called “schedulable”. An object can be scheduled with one or several Schedules. They describe its availability.

Schedules describe availability over multiple dimensions which contain all the possible states in which a client can be differentiated:

The availability is described as a subset of those dimensions:

As you can see in the figure above, two types of dimension are available in Skylark:

Time, where values are ordered and continuous and can be targeted in ranges
Discrete dimensions, where values have no relation to each other and must be targeted one by one

Here are the discrete dimensions on which Schedules are defined in Skylark.

Language: languages that users speak
Locale: countries (or other geographic areas) where the content is available
Region:region where the content is available (such asEMEA, North America, Cheshire…)
Device type: type of devices on which the content can be viewed
Affiliate: affiliate through which users can connect
Customer type: arbitrary set of groups that a customer can be part of

Notes about Schedules:

The discrete dimensions are fully customisable: they contain values customised to the needs of the product. This means, for instance, that a Skylark instance can start by supporting only English speaking visitors, and roll out other languages over time.

Schedules which have been ingested (called rights schedules) will have their rights attribute set to true, while the ones created in the CMS (called editorial schedules) will have their rights attribute set to false.

If no end date is specified on the timespan of a Schedule, it is valid from its start date indefinitely.

Filtering Scheduled Content

Skylark filters lists of scheduled content wherever they are included in API responses: the response of a list endpoint and also lists of related objects.

In this section, the method to specify the schedule filter context of a request is presented. Then, the process of filtering based on this context is explained. A method to ask Skylark to bypass filtering is finally given.

Specifying the context of a request

As seen above, Schedules are subsets of dimensions representing the time of a request and other variables. The context of a request is also a subset of the same dimensions. When filtering, Skylark finds Schedules that match with the request’s context.

Specifying context is done by adding arguments to GET requests. For instance the request represented in the diagram above is done by adding the following arguments:

?locales=fr,us&device_types=android&at=2000-03-12

Specifying subsets for the discrete dimensions is simple. All the values desired must be specified, separated by commas. Some Skylark installations will automatically infer some dimensions from the HTTP request, for example, by geolocating requests by IP.

?locales=fr,us&device_types=android

Specifying time filters is explained in a later section.

How Skylark filters a list of scheduled components

Objects are examined one by one. When examining an object, its schedules are checked for a match against the context individually. An object needs at least one matching schedule to be included in the filtered list.

In the above diagram, the second object is included in the filtered list because it is linked to one matching schedule. Note that it is also linked to a non-matching one.

For a schedule to match against a request context, the schedule must must match the context on a per dimension basis. There is always a match on a dimension when at least one of those two objects has no values specified. An object with no values specified on a dimension is considered as having no restrictions, and so matches the whole dimension.

The rules determining match of subsets on a dimension vary depending on the type of the dimension. For discrete dimensions, subsets match when they have at least one common value.

When matching time, the default behaviour is to match schedules that include the current time. Other schedules do not match.

Filtering is done on any list that is returned by Skylark, including Sets. However, the filtering process is slightly different for Set contents.

Sets contain other objects, sometime schedulable objects. But it is also possible to schedule their membership of the Set.

This is made possible by adding an intermediary object between the Set and the contained object: the ScheduledItem. The Set contains ScheduledItems and ScheduledItems refer to a single object.

As indicated by their name, ScheduledItems can be Scheduled. Items of a Set are returned if both their ScheduledItem containers and themselves match the request’s context.

Advanced Filtering: Filtering by time

Filtering by time isn’t available to general users. It is an administrative function that requires permissions to be granted to the user from their role.

First, let’s see how to specify a subset of the time dimension. It is possible to specify a timespan or a single date. This is done in two steps:

Specify a date with the keyword at on the request. If this step is ignored, at is set to the current time.

Two choices:

Specify a second date with the until keyword. This specifies a range between at and until
Specify when the desired content is scheduled relative to at with the keywords expired, current and future (their meaning is explained in the section below). They can be combined.

Then let’s see how the subsets on time dimensions are matched. It depends on how the context is defined. If the context is defined using current, expired and/or future, the dimensions matching are explained by the following diagram:

If the context is defined using until, schedules starting after at and ending before until will be matched.

Bypassing filtering

Here are three keywords arguments for GET request bypassing the normal filtering process. Again, these are only available to users with appropriate permissions.

Definition	Description
`all`	Returns all Objects
`unscheduled`	Returns all Objects not linked to any Schedule
`schedule_url`	Returns all Objects linked to the given Schedule(s)

Components

Added to Schedulable Objects

The following fields are added to the JSON representation of Schedulable objects:

schedule_urls: list the URL of all the schedules associated with the object
schedule_statuses: list the schedules associated with the object and whether they match the request context

Added to All Endpoints

It is possible to add these filters to all requests to Skylark. They take effect only when making requests for Schedulable objects. Please refer to the Technical Description for more information.

Definition	Description
`at`	Indicate the base date for the matching the time dimension. Defaults to the current time. ISO 8601 Timestamp
`until`	Establish a range between at and until for range-matching time. Default unset, to match a point in time.
`current`	Objects currently Scheduled are returned. Default to True
`expired`	Objects scheduled in the past are returned. Default to False. Boolean
`future`	Objects scheduled currently or in the future are returned. Default to False. Boolean
`languages`	Slugs of the language dimensions to match
`locales`	Slugs of the locales to match
`regions`	Slugs of the regions to match
`device_types`	Slugs of the device types to match
`affiliates`	Slugs of the affiliates to match
`customer_types`	Slugs of the customer types to match

For example,

/api/images/?affiliates=bbc,cnn

will filter a list of Images whose schedules are valid for the Affilliates bbc or cnn.

/api/episodes/?current=true&future=true

will return all Episodes that have a Schedule that has started but not ended, as well as any episodes that have a Schedule that will end in the future.

/api/sets/?expired=true&future=true

will return all Sets that have a Schedule which has ended and all Objects which have a schedule that ends in the future.

The at keyword can be used together with the expired, current and future keywords, for example:

/api/seasons/?at=2000-01-01T00:00:00¤t=true
/api/seasons/?at=2000-01-01T00:00:00

Both of the above calls return the same data, all the Seasons that have a current Schedule on 1st January 2000.

/api/seasons/?at=2000-01-01T00:00:00&future=true

This will return all the Seasons which have Schedules ending after the 1st January, 2000