Developers
How can we help you?
Rule
Mediagenix On-Demand’s rules let you define how to schedule your series or features for catch-up taking the transmissions in your linear channels as a reference
This is how a rule looks like:
<?xml version="1.0" encoding="UTF-8"?>
<rule>
<id type="integer">4</id>
<external-id nil="true"/>
<transmission-type>play_run</transmission-type>
<reference-tx-nth>1</reference-tx-nth>
<reference-tx-from type="datetime">2010-01-07T00:00:00Z</reference-tx-from>
<reference-tx-to type="datetime">2011-01-07T23:59:00Z</reference-tx-to>
<day-part-from>10:00</day-part-from>
<day-part-to>11:00</day-part-to>
<starts type="datetime">2010-10-10T00:00:00Z</starts>
<ends type="datetime">2021-10-10T23:59:00Z</ends>
<episode-selection-type>only</episode-selection-type>
<episode-selection>1,7-9</episode-selection>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/4"/>
<link rel="content" href="https://movida.bebanjo.net/api/title_groups/1"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/4/specific_platforms"/>
</rule>
{
"resource_type": "rule",
"id": 4,
"external_id": null,
"transmission_type": "play_run",
"reference_tx_nth": "1",
"reference_tx_from": "2010-01-07T00:00:00Z",
"reference_tx_to": "2011-01-07T23:59:00Z",
"day_part_from": "10:00",
"day_part_to": "11:00",
"starts": "2010-10-10T00:00:00Z",
"ends": "2010-10-10T23:59:00Z",
"episode_selection_type": "except",
"episode_selection": "1,7-9",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/4",
"content_link": "https://movida.bebanjo.net/api/title_groups/1",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/4/specific_platforms"
}
Valid attributes
-
id
(required): Mediagenix On-Demand internal identifier of the rule. -
external-id
(optional): identifier of the rule in the external system. -
starts
(optional): timestamp representing when the rule starts; only present if a specific starting date has been set for the rule. -
ends
(optional): timestamp representing when the rule ends; only present if a specific ending date has been set for the rule. -
start-offset-value
(optional): define when the rule starts. Allowed values are positive integers. If specified you need to provide<start-offset-unit>
and<start-offset-reference>
to define the start completely. -
start-offset-unit
(optional): define when the rule starts. Allowed values are: minutes, hours, days, weeks, months, years. If specified you need to provide<start-offset-value>
and<start-offset-reference>
to define the start completely. -
start-offset-reference
(optional): define when the rule starts. Allowed values are: before_tx_starts, after_tx_starts, after_tx_ends, after_last_episode_starts and after_last_episode_ends. If specified you need to provide<start-offset-value>
and<start-offset-reference>
to define the start completely. -
start-fixed-time
(optional): define when the rule starts at a given hour. Values for this field should be provided in the format “hh:mm”. This attribute can only be set whenstart-offset-unit
is set to days, weeks, months, years. -
end-offset-value
(optional): define when the rule ends. Allowed values are positive integers. If specified you need to provide<end-offset-unit>
and<end-offset-reference>
to define the end completely. -
end-offset-unit
(optional): define when the rule ends. Allowed values are: minutes, hours, days, weeks, months, years. If specified you need to provide<end-offset-value>
and<end-offset-reference>
to define the end completely. -
end-offset-reference
(optional): define when the rule ends. Allowed values are: after_start, after_tx_ends and after_last_episode. If specified you need to provide<end-offset-value>
and<end-offset-unit>
to define the end completely. -
end-fixed-time
(optional): define when the rule ends at a given hour. Values for this field should be provided in the format “hh:mm”. This attribute can only be set when<end-offset-unit>
is set to days, weeks, months, years. reference-tx-nth
(required): ordinal value representing what linear schedulings will be used. Allowed values are: all, a specific number or a range of numbers, separating the numbers by commas or by a dash. A dash range means that all the numbers in that range are included. Can’t be longer than 255 characters.-
all
includes all the numbers -
8
includes only the number 8 -
1,3-5,7,9
range includes the numbers 1, 3, 4, 5, 7 and 9 -
1-3,9,11-13
range includes the numbers 1, 2, 3, 9, 11, 12 and 13
-
transmission-type
(required): define the transmission type criteria to select the linear scheduling that will be used. Can take the following values:play_run
: consider the play run number of linear schedulings, which is the transmission number of the linear schedulings across linear channels.costed_run
: consider the run number in contract of linear schedulings, which is the costed run of the linear schedulings across linear channels.rerun
: consider the number of reruns of a linear scheduling.
Note: Deprecated feature.
Currently when no
transmission-type
is specified the valueplay_run
is taken as default. Theplay_run
value matches the transmission selection criteria present before thetransmission-type
attribute was available in the API.Please note that this behaviour is deprecated, and you shouldn’t rely on it in your integration. In the future, you will get an error when creating a rule without explicitly setting the
transmission-type
to be used.-
linear-contract-id
(optional): an unique identifier for a Linear contract. It allows to target costed run and reruns for the Linear contract specified. This attribute only makes sense when<transmission-type>
has the valuecosted_run
orrerun
. Can’t be longer than 255 characters. -
include-reruns
(optional): this attribute only makes sense when<transmission-type>
has the valuecosted_run
. It allows to target reruns per costed run, eg. to use linear schedulings withrerun
attribute included ininclude-reruns
value. Allowed values are:all
, a specific number or a range of numbers, separating the numbers by commas or by a dash. A dash range means that all the numbers in that range are included. Can’t be longer than 255 characters. -
reference-tx-from
(optional): timestamp representing what linear schedulings will be taken into account using theirbegins-at
attribute. -
reference-tx-to
(optional): timestamp representing what linear schedulings will be taken into account using theirends-at
attribute. asset-selection-type
(optional): define the default asset to be selected on catchup schedulings. Can take the following values:- Empty string: The asset of the catchup scheduling is kept in sync with the linear transmission asset.
- An asset type value: The asset of the catchup scheduling is kept in sync with the most recent asset of the given type. If no asset of that type is present then no asset is assigned.
This attribute is only present when asset types are defined. Please, contact your Technical Account Manager in order to define the list of asset types suitable for your company.
When the attribute is not present the default behaviour is according to the empty string value.
-
episode-selection-type
(optional): this attribute only makes sense for rules defined on series or collections. Can take three different values:-
all
: the rule applies to all episodes in the series or all titles in the collection. -
all-at-once
: the rule applies to all episodes in the series or all titles in the collection at once. If specified you can provide a different transmission content through the link identified by therel="transmission_content"
attribute. -
only
: the rule applies to the episode/title specified in the attribute<episode-selection>
. -
except
: the rule applies to all episodes/title except those specified in the attribute<episode-selection>
.
-
-
episode-selection
(optional): this attribute only makes sense when<episode-selection-type>
has the valuesonly
orexcept
. Its purpose is to specify a range of episodes/titles, separating the episode numbers by commas or by a dash. A dash range means that all the episodes in that range are included. Can’t be longer than 255 characters. For example:-
1,3-5,7,9
range includes the episodes 1, 3, 4, 5, 7 and 9 -
1-3,9,11-13
range includes the episodes 1, 2, 3, 9, 11, 12 and 13
-
-
day-part-from
(optional): a time value in the format “hh:mm”. Combined with<day-part-to>
, defines the time window during which the rule should be applied. For example: if<day-part-from>
has a value of “10:00” and<day-part-to>
has a value of “11:00”, the rule will only apply on transmissions happening between 10:00 and 11:00 each day. day-part-to
(optional): see<day-part-from>
above for more details.
Get a list of all rules in the current account
Rules are linked from the root of the API, through the link identified with the rel="rules"
attribute:
<?xml version="1.0" encoding="UTF-8"?>
<movida>
<!-- ... -->
<link rel="rules" href="https://movida.bebanjo.net/api/rules"/>
</movida>
{
// ...
"rules_link": "https://movida.bebanjo.net/api/rules",
// ...
}
Following that link, we can fetch the list of rules in the current account.
$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/rules?page=2
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/rules?page=2
<?xml version="1.0" encoding="UTF-8"?>
<rules type="array">
<total-entries>113</total-entries>
<link rel="next" href="https://movida.bebanjo.net/api/rules?page=1"/>
<link rel="prev" href="https://movida.bebanjo.net/api/rules?page=3"/>
<rule>
<id type="integer">5</id>
<external-id>RR12-5</external-id>
<!-- ... -->
</rule>
<rule>
<id type="integer">6</id>
<external-id>RR11-5</external-id>
<!-- ... -->
</rule>
<!-- ... -->
<rules>
{
"total_entries": 113,
"prev_link": "https://movida.bebanjo.net/api/rules?page=1",
"next_link": "https://movida.bebanjo.net/api/rules?page=3",
"entries": [
{
"resource_type": "rule",
"id": 5,
"external_id": "RR12-5",
// ...
},
{
"resource_type": "rule",
"id": 6,
"external_id": "RR11-5",
// ...
}
// ...
]
}
Note: This is a paginated resource. By default, only 50 Rules will be included in each page but you can override this default by using the
per_page
parameter described in the next section. Thetotal-entries
attribute will indicate the total number of entries and the linksrel="next"
andrel="prev"
should be used to get the next and the previous pages.
Valid attributes
You can filter the list of Rules returned using the following parameters:
-
external_id
: It will return only the Rule with the exact given external_id (if any). -
per_page
: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50. -
page
: Number of the page you want to be returned.
Get a list of rules from a feature, series or collection
Given an existing feature, for example:
<title>
<id type="integer">12</id>
<name>Silicon Computers</name>
<title>Silicon Computers</title>
<external-id nil="true"/>
<title-type>feature</title-type>
<tags></tags>
<link rel="self" href="https://movida.bebanjo.net/api/titles/12"/>
<link rel="schedule" href="https://movida.bebanjo.net/api/titles/12/schedule"/>
<link rel="availability_windows" href="https://movida.bebanjo.net/api/titles/12/availability_windows"/>
<link rel="title_groups" href="https://movida.bebanjo.net/api/titles/12/title_groups"/>
<link rel="licensor" href="https://movida.bebanjo.net/api/licensors/114"/>
<link rel="images" href="https://movida.bebanjo.net/api/titles/12/images"/>
<link rel="assets" href="https://movida.bebanjo.net/api/titles/12/assets"/>
<link rel="metadata" href="https://movida.bebanjo.net/api/titles/12/metadata"/>
<link rel="blackouts" href="https://movida.bebanjo.net/api/titles/12/blackouts"/>
<link rel="rights" href="https://movida.bebanjo.net/api/titles/12/rights"/>
<link rel="denied_rights" href="https://movida.bebanjo.net/api/titles/12/denied_rights"/>
<link rel="rules" href="https://movida.bebanjo.net/api/titles/12/rules"/>
<link rel="trailers" href="https://movida.bebanjo.net/api/titles/12/trailers"/>
</title>
{
"resource_type": "title",
"id": 12,
"name": "Silicon Computers",
"title": "Silicon Computers",
"external_id": null,
"title_type": "feature",
"tags": "",
"self_link": "https://movida.bebanjo.net/api/titles/12",
"schedule_link": "https://movida.bebanjo.net/api/titles/12/schedule",
"linear_schedulings_link": "https://movida.bebanjo.net/api/titles/12/linear_schedulings",
"availability_windows_link": "https://movida.bebanjo.net/api/titles/12/availability_windows",
"title_groups_link": "https://movida.bebanjo.net/api/titles/12/title_groups",
"licensor_link": "https://movida.bebanjo.net/api/licensors/114",
"images_link": "https://movida.bebanjo.net/api/titles/12/images",
"assets_link": "https://movida.bebanjo.net/api/titles/12/assets",
"metadata_link": "https://movida.bebanjo.net/api/titles/12/metadata",
"blackouts_link": "https://movida.bebanjo.net/api/titles/12/blackouts",
"rights_link": "https://movida.bebanjo.net/api/titles/12/rights",
"denied_rights_link": "https://movida.bebanjo.net/api/titles/12/denied_rights",
"rules_link": "https://movida.bebanjo.net/api/titles/12/rules",
"clips_link": "https://movida.bebanjo.net/api/titles/12/clips",
"note_link": "https://movida.bebanjo.net/api/titles/12/note"
}
All the rules of that feature can be obtained by following the link rel="rules"
:
$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/titles/12/rules
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/titles/12/rules
<rules type="array">
<rule>
<id type="integer">7</id>
<external-id>FR2</external-id>
<!-- ... -->
<starts type="datetime">2013-10-10T00:00:00Z</starts>
<ends type="datetime">2014-10-10T23:59:00Z</ends>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/7"/>
<link rel="content" href="https://movida.bebanjo.net/api/titles/12"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/7/specific_platforms"/>
</rule>
<rule>
<id type="integer">8</id>
<!-- ... -->
<starts type="datetime">2011-11-10T00:00:00Z</starts>
<ends type="datetime">2012-10-10T23:59:00Z</ends>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/8"/>
<link rel="content" href="https://movida.bebanjo.net/api/titles/12"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/8/specific_platforms"/>
</rule>
</rules>
{
"total_entries": 2,
"entries": [
{
"resource_type": "rule",
"id": 7,
"external_id": "FR2",
// ...
"starts": "2013-10-10T00:00:00Z",
"ends": "2014-10-10T23:59:00Z",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/7",
"content_link": "https://movida.bebanjo.net/api/titles/12",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/7/specific_platforms"
},
{
"resource_type": "rule",
"id": 8,
"external_id": null,
// ...
"starts": "2011-11-10T00:00:00Z",
"ends": "2012-10-10T23:59:00Z",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/8",
"content_link": "https://movida.bebanjo.net/api/titles/12",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/8/specific_platforms"
}
]
}
Get a single rule
Just do a GET
to the URI of the rule (the one in the attribute rel="self"
):
$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/rules/6
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/rules/6
<?xml version="1.0" encoding="UTF-8"?>
<rule>
<id type="integer">6</id>
<external-id>RR12-5</external-id>
<transmission-type>play_run</transmission-type>
<reference-tx-nth>1</reference-tx-nth>
<reference-tx-from nil="true"/>
<reference-tx-to nil="true"/>
<day-part-from nil="true"/>
<day-part-to nil="true"/>
<starts type="datetime">2013-01-10T00:00:00Z</starts>
<ends type="datetime">2015-01-10T23:59:00Z</ends>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/6"/>
<link rel="content" href="https://movida.bebanjo.net/api/titles/3"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/6/specific_platforms"/>
</rule>
{
"resource_type": "rule",
"id": 6,
"external_id": "RR12-5",
"transmission_type": "play_run",
"reference_tx_nth": "1",
"reference_tx_from": null,
"reference_tx_to": null,
"day_part_from": null,
"day_part_to": null,
"starts": "2013-01-10T00:00:00Z",
"ends": "2015-01-10T23:59:00Z",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/6",
"content_link": "https://movida.bebanjo.net/api/titles/3",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/6/specific_platforms"
}
Creating a rule inside a feature
As our introduction to REST APIs page suggests, you can create a rule issuing a POST
request to each rule URI:
$ cat rule_create.xml
$ cat rule_create.json
<rule>
<external-id>RR12-5</external-id>
<starts type="date">2013-01-09</starts>
<ends type="date">2015-01-10T00:00</ends>
<reference-tx-nth>1</reference-tx-nth>
<transmission-type>play_run</transmission-type>
</rule>
{
"external_id": "RR12-5",
"starts": "2013-01-09",
"ends": "2015-01-10T00:00",
"reference_tx_nth": 1,
"transmission_type": "play_run"
}
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @rule_create.xml "https://movida.bebanjo.net/api/titles/1/rules"
$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @rule_create.json "https://movida.bebanjo.net/api/titles/1/rules"
As always Mediagenix On-Demand will return the full XML/JSON of the rule just created:
<?xml version="1.0" encoding="UTF-8"?>
<rule>
<id type="integer">13</id>
<external-id>RR12-5</external-id>
<transmission-type>play_run</transmission-type>
<reference-tx-nth>1</reference-tx-nth>
<reference-tx-from nil="true"/>
<reference-tx-to nil="true"/>
<linear-contract-id nil="true"/>
<include-reruns nil="true"/>
<day-part-from nil="true"/>
<day-part-to nil="true"/>
<starts type="datetime">2013-01-09T00:00:00Z</starts>
<ends type="datetime">2015-01-10T00:00:00Z</ends>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/13"/>
<link rel="content" href="https://movida.bebanjo.net/api/titles/1"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/13/specific_platforms"/>
</rule>
{
"resource_type": "rule",
"id": 13,
"external_id": "RR12-5",
"transmission_type": "play_run",
"reference_tx_nth": "1",
"reference_tx_from": null,
"reference_tx_to": null,
"linear_contract_id": null,
"include_reruns": null,
"day_part_from": null,
"day_part_to": null,
"starts": "2013-01-09T00:00:00Z",
"ends": "2015-01-10T00:00:00Z",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/13",
"content_link": "https://movida.bebanjo.net/api/titles/1",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/13/specific_platforms"
}
Creating a rule inside a title group
As our introduction to REST APIs page suggests, you can create a rule issuing a POST
request to each rule URI:
$ cat rule_create.xml
$ cat rule_create.json
<rule>
<external-id>RR12-6</external-id>
<starts type="date">2013-01-10</starts>
<ends type="date">2015-01-10T00:00</ends>
<reference-tx-nth>1</reference-tx-nth>
<transmission-type>play_run</transmission-type>
</rule>
{
"external_id": "RR12-6",
"starts": "2013-01-09",
"ends": "2015-01-10T00:00",
"reference_tx_nth": 3,
"transmission_type": "play_run"
}
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @rule_create.xml "https://movida.bebanjo.net/api/title_groups/1/rules"
$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @rule_create.json "https://movida.bebanjo.net/api/title_groups/1/rules"
As always Mediagenix On-Demand will return the full XML/JSON of the rule just created:
<?xml version="1.0" encoding="UTF-8"?>
<rule>
<id type="integer">14</id>
<external-id>RR12-6</external-id>
<transmission-type>play_run</transmission-type>
<reference-tx-nth>1</reference-tx-nth>
<reference-tx-from nil="true"/>
<reference-tx-to nil="true"/>
<linear-contract-id nil="true"/>
<include-reruns nil="true"/>
<day-part-from nil="true"/>
<day-part-to nil="true"/>
<starts type="datetime">2013-01-09T00:00:00Z</starts>
<ends type="datetime">2015-01-10T00:00:00Z</ends>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/14"/>
<link rel="content" href="https://movida.bebanjo.net/api/title_groups/1"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/14/specific_platforms"/>
</rule>
{
"resource_type": "rule",
"id": 14,
"external_id": "RR12-6",
"transmission_type": "play_run",
"reference_tx_nth": "1",
"reference_tx_from": null,
"reference_tx_to": null,
"linear_contract_id": null,
"include_reruns": null,
"day_part_from": null,
"day_part_to": null,
"starts": "2013-01-09T00:00:00Z",
"ends": "2015-01-10T00:00:00Z",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/14",
"content_link": "https://movida.bebanjo.net/api/titles/1",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/14/specific_platforms"
}
Updating a rule
As our introduction to REST APIs page suggests, you can update a rule issuing a PUT
request to each rule URI:
$ cat rule_update.xml
$ cat rule_update.json
<rule>
<episode-selection-type>only</episode-selection-type>
<episode-selection>1,2</episode-selection>
</rule>
{
"episode_selection_type": "only",
"episode_selection": "1,2"
}
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @rule_update.xml "https://movida.bebanjo.net/api/rules/13"
$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @rule_update.json "https://movida.bebanjo.net/api/rules/13"
As always Mediagenix On-Demand will return the full XML/JSON of the rule just updated:
<?xml version="1.0" encoding="UTF-8"?>
<rule>
<id type="integer">14</id>
<external-id>RR12-6</external-id>
<transmission-type>play_run</transmission-type>
<reference-tx-nth>1</reference-tx-nth>
<reference-tx-from nil="true"/>
<reference-tx-to nil="true"/>
<day-part-from nil="true"/>
<day-part-to nil="true"/>
<starts type="datetime">2013-01-10T00:00:00Z</starts>
<ends type="datetime">2015-01-10T00:00:00Z</ends>
<episode-selection-type>only</episode-selection-type>
<episode-selection>1,2</episode-selection>
<asset-selection-type nil="true"/>
<link rel="self" href="https://movida.bebanjo.net/api/rules/14"/>
<link rel="content" href="https://movida.bebanjo.net/api/title_groups/1"/>
<link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/14/specific_platforms"/>
</rule>
{
"resource_type": "rule",
"id": 14,
"external_id": "RR12-6",
"transmission_type": "play_run",
"reference_tx_nth": "1",
"reference_tx_from": null,
"reference_tx_to": null,
"day_part_from": null,
"day_part_to": null,
"starts": "2013-01-10T00:00:00Z",
"ends": "2015-01-10T00:00:00Z",
"episode_selection_type": "only",
"episode_selection": "1,2",
"asset_selection_type": null,
"self_link": "https://movida.bebanjo.net/api/rules/14",
"content_link": "https://movida.bebanjo.net/api/title_groups/1",
"specific_platforms_link": "https://movida.bebanjo.net/api/rules/14/specific_platforms"
}
Deleting a rule
Also you can delete a rule using DELETE
request to each rule URI:
$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/rules/13"
$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/rules/13"
The DELETE
request doesn’t return anything, as that rule is now gone.