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
## 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.
When creating/updating a schedule by giving the schedule data:
1. Projected timeslots are matched against existing timeslots
2. API returns an array of objects containing
2.1. the schedule's data
2.2. projected timeslots (array of objects), including an array of found collisions (objects) and possible solutions (array)
3. To resolve, POST/PUT the schedule object and the solutions objects to /api/v1/shows/{show_pk}/schedules/{schedule_pk}/
2.2. projected timeslots (array of objects), including an array of found collisions (objects) and
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
* To create: POST
/api/v1/shows/{show_pk}/schedules/
* To create: POST `/api/v1/shows/{show_pk}/schedules/`
* To update: PUT
/api/v1/shows/{show_pk}/schedules/{schedule_pk}/
* To update: PUT `/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 |
|------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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 |
| dstart* | date | Start date of schedule | (e.g. 2017-01-01) |
| tstart* | time | Start time of schedule | (e.g. 16:00:00) |
| tend* | time | End time of schedule (e.g. 17:00:00) |
| until* | date | End date of schedule (e.g. 2017-12-31) |
| first_date* | date | Start date of schedule (e.g. "2017-01-01") |
| start_time* | time | Start time of schedule (e.g. "16:00:00") |
| end_time* | time | End time of schedule (e.g. "17:00:00") |
| last_date** | date | End date of schedule (e.g. "2017-12-31") |
| 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) |
| show* | int | Show the schedule belongs to |
......@@ -39,9 +61,13 @@ To start the conflict resolution POST/PUT the schedule object with key 'schedule
__*__ = 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
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
{
......@@ -62,7 +88,7 @@ After sending the schedule's data, there'll be a return in the form of:
"show_name": "FROzine",
"is_repetition": false,
"schedule": 42,
"memo": ""
"memo": "",
"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:
/* The schedule's data is mandatory for each POST/PUT */
"schedule": {
"rrule": 4,
"byweekday": 1,
"by_weekday": 1,
"show": 3,
"dstart": "2018-01-16",
"tstart": "14:30:00",
"tend": "16:00:00",
"until": "2018-06-28",
"first_date": "2018-01-16",
"start_time": "14:30:00",
"end_time": "16:00:00",
"last_date": "2018-06-28",
"is_repetition": false,
"default_playlist_id": null,
"automation_id": null,
......@@ -107,58 +133,62 @@ After sending the schedule's data, there'll be a return in the form of:
## 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:
```json
"solutions": [
"theirs",
"ours",
"theirs-start",
"ours-start",
"theirs-end",
"ours-end",
"theirs-both",
"ours-both"
]
"solutions": [
"theirs",
"ours",
"theirs-start",
"ours-start",
"theirs-end",
"ours-end",
"theirs-both",
"ours-both"
]
```
### theirs (always possible)
### `"theirs"` (always possible)
* Discard projected timeslot
* Keep existing timeslot(s)
### ours (always possible)
### `"ours"` (always possible)
* Create projected timeslot
* Delete existing timeslot(s)
### theirs-start
### `"theirs-start"`
* Keep existing timeslot
* Create projected timeslot with start time of existing end
### ours-start
### `"ours-start"`
* Create projected timeslot
* Change end of existing timeslot to projected start time
### theirs-end
### `"theirs-end"`
* Keep existing timeslot
* Create projected timeslot with end of existing start time
### ours-end
### `"ours-end"`
* Create projected timeslot
* Change start of existing timeslot to projected end time
### theirs-both
### `"theirs-both"`
* Keep existing timeslot
* Create two projected timeslots with end of existing start and start of existing end
### ours-both
### `"ours-both"`
* Create projected timeslot
* Split existing into two:
* Set existing end time to projected start
......@@ -166,7 +196,8 @@ Maximum possible output:
#### 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
......@@ -174,19 +205,29 @@ Possible error messages are:
### 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.
* '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)
* 'Numbers of conflicts and solutions don't match':
* `"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)
* `"Numbers of conflicts and solutions don't match"`:
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 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:
* 'No solution given':
The 'solutions'-value was empty or does not exist. Provide a value of 'solution_choices'
* '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')
* `"No solution given"`:
The solutions value was empty or does not exist. Provide a value of `solution_choices`
* `"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"`)
## 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