## What is it? 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 * Personalize 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 divinding the userbase 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 customizable: 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 behavior 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: 1. Specify a date with the keyword `at` on the request. If this step is ignored, `at` is set to the current time. 1. Two choices: 1. Specify a second date with the `until` keyword. This specifies a range between `at` and `until` 1. 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, ```no-highlight /api/images/?affiliates=bbc,cnn ``` will filter a list of Images whose schedules are valid for the Affilliates `bbc` or `cnn`. ```no-highlight /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. ```no-highlight /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: ```no-highlight /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. ```no-highlight /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