Commit a3c39495 authored by Ernesto Rico Schmidt's avatar Ernesto Rico Schmidt
Browse files

Update documentation for conflict resolution

- Clarify the behavior when `last_date` is not specified
- Update the properties to match the current state of the Steering API
parent c52f7cd5
<img src="../../assets/images/aura-logo.png" width="250" />
# Schedules and conflict resolution # Schedules and conflict resolution
## Overview [← Developer Guide | Overview](index.md)
1. [Schedules and conflict resolution](#schedules-and-conflict-resolution)
1. [Overview](#overview)
2. [Create/update schedule](#createupdate-schedule)
3. [Return](#return)
4. [Solutions](#solutions)
1. [theirs (always possible)](#theirs-always-possible)
2. [ours (always possible)](#ours-always-possible)
3. [theirs-start](#theirs-start)
4. [ours-start](#ours-start)
5. [theirs-end](#theirs-end)
6. [ours-end](#ours-end)
7. [theirs-both](#theirs-both)
8. [ours-both](#ours-both)
1. [Multiple collisions](#multiple-collisions)
5. [Errors](#errors)
1. [Fatal errors that require the schedule's data to be corrected and the resolution to restart](#fatal-errors-that-require-the-schedules-data-to-be-corrected-and-the-resolution-to-restart)
2. [Conflict-related errors which can be resolved for each conflict:](#conflict-related-errors-which-can-be-resolved-for-each-conflict)
6. [Read more](#read-more)
## Overview
Creating timeslots is only possible by creating/updating a schedule. Creating timeslots is only possible by creating/updating a schedule.
When creating/updating a schedule by giving the schedule data: When creating/updating a schedule by giving the schedule data:
1. Projected timeslots are matched against existing timeslots 1. Projected timeslots are matched against existing timeslots
2. API returns an array of objects containing 2. API returns an array of objects containing
2.1. the schedule's data 2.1. the schedule's data
2.2. projected timeslots (array of objects), including an array of found collisions (objects) and possible solutions (array) 2.2. projected timeslots (array of objects), including an array of found collisions (objects) and
3. To resolve, POST/PUT the schedule object and the solutions objects to /api/v1/shows/{show_pk}/schedules/{schedule_pk}/ possible solutions (array)
3. To resolve, POST/PUT the `"schedule"` object and the `"solutions"` objects to
`/api/v1/shows/{show_pk}/schedules/{schedule_pk}/`
## Create/update schedule ## Create/update schedule
* To create: POST * To create: POST `/api/v1/shows/{show_pk}/schedules/`
/api/v1/shows/{show_pk}/schedules/
* To update: PUT * To update: PUT `/api/v1/shows/{show_pk}/schedules/{schedule_pk}/`
/api/v1/shows/{show_pk}/schedules/{schedule_pk}/
To start the conflict resolution POST/PUT the schedule object with key 'schedule' containing: To start the conflict resolution POST/PUT the schedule object with key `"schedule"` containing:
| Variable | Type | Meaning | | Variable | Type | Meaning |
|------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| byweekday* | int | Weekday number: Mon = 0, Sun = 6 | | by_weekday* | int | Weekday number: Mon = 0, Sun = 6 |
| rrule* | int | Recurrence rule: 1 = once, 2 = daily, 3 = business days, 4 = weekly, 5 = biweekly, 6 = every four weeks, 7 = every even calendar week (ISO 8601), 8 = every odd calendar week (ISO 8601), 9 = every 1st week of month, 10 = every 2nd week of month, 11 = every 3rd week of month, 12 = every 4th week of month, 13 = every 5th week of month | | rrule* | int | Recurrence rule: 1 = once, 2 = daily, 3 = business days, 4 = weekly, 5 = biweekly, 6 = every four weeks, 7 = every even calendar week (ISO 8601), 8 = every odd calendar week (ISO 8601), 9 = every 1st week of month, 10 = every 2nd week of month, 11 = every 3rd week of month, 12 = every 4th week of month, 13 = every 5th week of month |
| dstart* | date | Start date of schedule | (e.g. 2017-01-01) | | first_date* | date | Start date of schedule (e.g. "2017-01-01") |
| tstart* | time | Start time of schedule | (e.g. 16:00:00) | | start_time* | time | Start time of schedule (e.g. "16:00:00") |
| tend* | time | End time of schedule (e.g. 17:00:00) | | end_time* | time | End time of schedule (e.g. "17:00:00") |
| until* | date | End date of schedule (e.g. 2017-12-31) | | last_date** | date | End date of schedule (e.g. "2017-12-31") |
| is_repetition | boolean | Whether the schedule is a repetition (default: false) | | is_repetition | boolean | Whether the schedule is a repetition (default: false) |
| default_playlist_id | int | A tank ID in case the timeslot's playlist_id is empty: What is aired if a single timeslot has no content? (default: null) | | default_playlist_id | int | A tank ID in case the timeslot's playlist_id is empty: What is aired if a single timeslot has no content? (default: null) |
| show* | int | Show the schedule belongs to | | show* | int | Show the schedule belongs to |
...@@ -39,9 +61,13 @@ To start the conflict resolution POST/PUT the schedule object with key 'schedule ...@@ -39,9 +61,13 @@ To start the conflict resolution POST/PUT the schedule object with key 'schedule
__*__ = required __*__ = required
__**__ = if `last_date` is not provided, timeslots will be generated until the end of the year if
`AUTO_SET_LAST_DATE_TO_END_OF_YEAR` is `True`, otherwise timeslots will be generated until
`AUTO_SET_LAST_DATE_TO_DAYS_IN_FUTURE` after the `start_date` **and** `end_date` will remain unset.
## Return ## Return
After sending the schedule's data, there'll be a return in the form of: After sending the schedule's data, the response will be in the form of:
```json ```json
{ {
...@@ -62,7 +88,7 @@ After sending the schedule's data, there'll be a return in the form of: ...@@ -62,7 +88,7 @@ After sending the schedule's data, there'll be a return in the form of:
"show_name": "FROzine", "show_name": "FROzine",
"is_repetition": false, "is_repetition": false,
"schedule": 42, "schedule": 42,
"memo": "" "memo": "",
"note_id": 1 /* A note assigned to the timeslot. May not exist */ "note_id": 1 /* A note assigned to the timeslot. May not exist */
} }
], ],
...@@ -91,12 +117,12 @@ After sending the schedule's data, there'll be a return in the form of: ...@@ -91,12 +117,12 @@ After sending the schedule's data, there'll be a return in the form of:
/* The schedule's data is mandatory for each POST/PUT */ /* The schedule's data is mandatory for each POST/PUT */
"schedule": { "schedule": {
"rrule": 4, "rrule": 4,
"byweekday": 1, "by_weekday": 1,
"show": 3, "show": 3,
"dstart": "2018-01-16", "first_date": "2018-01-16",
"tstart": "14:30:00", "start_time": "14:30:00",
"tend": "16:00:00", "end_time": "16:00:00",
"until": "2018-06-28", "last_date": "2018-06-28",
"is_repetition": false, "is_repetition": false,
"default_playlist_id": null, "default_playlist_id": null,
"automation_id": null, "automation_id": null,
...@@ -107,58 +133,62 @@ After sending the schedule's data, there'll be a return in the form of: ...@@ -107,58 +133,62 @@ After sending the schedule's data, there'll be a return in the form of:
## Solutions ## Solutions
The 'solution_choices' array contains possible solutions to the conflict. The `"solution_choices"` array contains possible solutions to the conflict.
To solve conflicts, POST the schedule and solutions objects to /api/v1/shows/{show_p}/schedules/ or PUT to /api/v1/shows/{show_pk}/schedules/{schedule_pk}/ with 'solutions' containing values of solution_choices. Any other value will produce an error. To solve conflicts, POST the `"schedule"` and `"solutions"` objects to
`/api/v1/shows/{show_p}/schedules/` or PUT to `/api/v1/shows/{show_pk}/schedules/{schedule_pk}/`
with `"solutions"` containing values of `solution_choices`. Any other value will produce an error.
As long as there's an error, the whole data structure is returned and no database changes will occur. If resolution was successful, database changes take effect and the schedule is returned. As long as there's an error, the whole data structure is returned and no database changes will
occur. If resolution was successful, database changes take effect and the schedule is returned.
A Schedule is only created/updated if at least one timeslot was created during the resolution process. A Schedule is only created/updated if at least one timeslot was created during the resolution
process.
Maximum possible output: Maximum possible output:
```json ```json
"solutions": [ "solutions": [
"theirs", "theirs",
"ours", "ours",
"theirs-start", "theirs-start",
"ours-start", "ours-start",
"theirs-end", "theirs-end",
"ours-end", "ours-end",
"theirs-both", "theirs-both",
"ours-both" "ours-both"
] ]
``` ```
### theirs (always possible) ### `"theirs"` (always possible)
* Discard projected timeslot * Discard projected timeslot
* Keep existing timeslot(s) * Keep existing timeslot(s)
### ours (always possible) ### `"ours"` (always possible)
* Create projected timeslot * Create projected timeslot
* Delete existing timeslot(s) * Delete existing timeslot(s)
### theirs-start ### `"theirs-start"`
* Keep existing timeslot * Keep existing timeslot
* Create projected timeslot with start time of existing end * Create projected timeslot with start time of existing end
### ours-start ### `"ours-start"`
* Create projected timeslot * Create projected timeslot
* Change end of existing timeslot to projected start time * Change end of existing timeslot to projected start time
### theirs-end ### `"theirs-end"`
* Keep existing timeslot * Keep existing timeslot
* Create projected timeslot with end of existing start time * Create projected timeslot with end of existing start time
### ours-end ### `"ours-end"`
* Create projected timeslot * Create projected timeslot
* Change start of existing timeslot to projected end time * Change start of existing timeslot to projected end time
### theirs-both ### `"theirs-both"`
* Keep existing timeslot * Keep existing timeslot
* Create two projected timeslots with end of existing start and start of existing end * Create two projected timeslots with end of existing start and start of existing end
### ours-both ### `"ours-both"`
* Create projected timeslot * Create projected timeslot
* Split existing into two: * Split existing into two:
* Set existing end time to projected start * Set existing end time to projected start
...@@ -166,7 +196,8 @@ Maximum possible output: ...@@ -166,7 +196,8 @@ Maximum possible output:
#### Multiple collisions #### Multiple collisions
If there's more than one collision for a projected timeslot, only 'theirs' and 'ours' are currently supported as solutions. If there's more than one collision for a projected timeslot, only `"theirs"` and `"ours"` are
currently supported as solutions.
## Errors ## Errors
...@@ -174,19 +205,29 @@ Possible error messages are: ...@@ -174,19 +205,29 @@ Possible error messages are:
### Fatal errors that require the schedule's data to be corrected and the resolution to restart ### Fatal errors that require the schedule's data to be corrected and the resolution to restart
* 'Until date mustn't be before start': * `"Until date mustn't be before start"`:
Set correct start and until dates. Set correct start and until dates.
* 'Start and until dates mustn't be the same' * `"Start and until dates mustn't be the same"`
Set correct start and until dates. (Exception: Single timeslots with recurrence rule 'once' may have the same dates) Set correct start and until dates. (Exception: Single timeslots with recurrence rule 'once' may
* 'Numbers of conflicts and solutions don't match': have the same dates)
* `"Numbers of conflicts and solutions don't match"`:
There probably was a change in the schedule by another person in the meantime. There probably was a change in the schedule by another person in the meantime.
* 'This change on the timeslot is not allowed.' * `"This change on the timeslot is not allowed."`
When adding: There was a change in the schedule's data during conflict resolution. When adding: There was a change in the schedule's data during conflict resolution.
When updating: Fields 'start', 'end', 'byweekday' or 'rrule' have changed, which is not allowed. When updating: Fields `start`, `end`, `by_weekday` or `rrule` have changed, which is not allowed.
### Conflict-related errors which can be resolved for each conflict: ### Conflict-related errors which can be resolved for each conflict:
* 'No solution given': * `"No solution given"`:
The 'solutions'-value was empty or does not exist. Provide a value of 'solution_choices' The solutions value was empty or does not exist. Provide a value of `solution_choices`
* 'Given solution is not accepted for this conflict.': * `"Given solution is not accepted for this conflict."`:
The solution has a value which is not part of 'solution_choices'. Provide a value of 'solution_choices' (at least 'ours' or 'theirs') The solution has a value which is not part of `solution_choices`. Provide a value of
`solution_choices` (at least `"ours"` or `"theirs"`)
## Read more
* [User Guide](docs/user/index.md)
* [Installation Guide](docs/administration/installation-guide.md)
* [Maintenance Guide](docs/administration/maintenance-guide.md)
* [API Specification](docs/development/api-definition.md)
* [Conflict Resolution](docs/development/conflict_resolution.pdf)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment