Data model
Every Planning model with its important fields, constraints, public methods and the context keys that change behaviour, for developers.
This page is a reference for developers. Technical names are in code; the label shown to users is in quotes. Fields that only support the chatter (messages, followers, activities) and the portal mixin are omitted. See the diagram on Technical architecture.
Shift: smarterp.planning.shift#
Inherits mail.thread, mail.activity.mixin and portal.mixin. Order start_datetime, id desc. _check_company_auto is on.
| Field | Label | Type | Notes |
|---|---|---|---|
name | Note | Text | Free note shown to the employee. |
active | Boolean | Archived shifts are hidden. | |
company_id | Company | Many2one | Required; default the current company. |
resource_id | Resource | Many2one resource.resource | Empty means open shift. Indexed; tracked. |
resource_type | Type | Related | From the resource. |
user_id, employee_id, department_id | User, Employee, Department | Stored computed | From the resource. employee_id is limited to HR officers. |
role_id | Role | Many2one, stored computed, writable | Defaults from the template, or the resource's default role. Tracked. |
color | Related | Colour of the role. | |
template_id | Shift Template | Many2one | |
template_creation | Save as Template | Boolean, not stored | Creates a template on save. |
is_open_shift | Stored computed | not resource_id. | |
allocation_type | Allocation Type | Selection | planning (Shift) or forecast (Forecast). |
qualified_count | Qualified People | Computed | People holding the role (open shifts only). |
role_mismatch, role_mismatch_message | Wrong Role | Computed, searchable | |
manager_id | Shift Manager | Many2one res.users, stored computed, writable | Department manager's user, else the employee's manager's user. |
approval_state | Change Approval | Selection | none, waiting, approved, rejected. Not copied. |
reminder_sent_start | Datetime | Start time at the last reminder. Not copied. | |
start_datetime, end_datetime | Start, End | Datetime | Required, indexed, tracked; default today 08:00 and 17:00 in the user's zone. |
duration | Duration | Stored computed | Clock hours. |
working_hours | Working Hours | Stored computed | Hours inside the resource's valid work intervals. |
break_time | Break | Float | Hours. Not negative. |
allocated_percentage | Allocated Time % | Float | Default 100. |
allocated_hours | Allocated Time | Stored computed, writable | max(base × % − break, 0) where base = working_hours or duration. Not copied. |
is_past | Computed, searchable | end_datetime < now. | |
state | State | Selection | draft, published. |
publication_warning | Modified Since Last Publication | Boolean | Set when a PUBLICATION_FIELDS field changes on a published shift. |
was_copied | Copied to the Next Week | Boolean | Set on sources of Copy Previous Week. |
overlap_slot_count, conflicting_slot_ids | Overlapping Shifts | Computed, searchable | Other active planning shifts of the same resource that overlap. |
currency_id, cost | Cost | Monetary | allocated_hours × role.hourly_cost. |
recurrency_id | Many2one | The series. | |
repeat, repeat_interval, repeat_unit, repeat_type, repeat_until, repeat_number | Repeat... | Computed from the series, writable | Written values create or update the series. |
recurrence_update | Recurrence Update | Selection, not stored | this, subsequent, all. |
request_to_switch | Switch Requested | Boolean | Tracked; not copied. |
allow_self_unassign, self_unassign_days_before | Related to the company | ||
unassign_deadline, is_unassign_deadline_passed | Computed | ||
is_planning_manager, is_own_shift, can_self_assign, can_self_unassign, can_request_switch, can_take_switch | Computed, depend on the user | Drive form buttons and the card. | |
slot_properties | Properties | Properties | Definition on the role. |
PUBLICATION_FIELDS = resource_id, start_datetime, end_datetime, allocated_hours, allocated_percentage, role_id, break_time.
Constraints. SQL: check_start_before_end, check_allocated_hours_positive, check_allocated_percentage_positive, check_break_time_positive. Python: _check_dates, _check_forecast_resource. Index smarterp_planning_shift_resource_period_idx on (resource_id, start_datetime, end_datetime) where active.
Public methods.
| Method | Purpose |
|---|---|
action_publish, action_unpublish, action_send | Publish (with notifications and broadcast), unpublish, publish alias. Need _check_can_plan. |
action_approve_change, action_reject_change | Change approval. |
action_self_assign, action_self_unassign, action_request_switch, action_cancel_switch, action_take_switch | Self-service for the user's own resource. |
action_copy_previous_week(date_start, date_end, domain), action_auto_plan(date_start, date_end, domain) | Period operations. Managers only. |
get_planning_schedule_data, get_planning_card, get_planning_header_actions, get_planning_quick_create_defaults, get_planning_to_plan_items, planning_user_can_plan | Data for the schedule view. |
planning_check_drop, planning_eligibility_map, planning_snapshot, planning_restore, planning_drop_item, action_planning_copy_to, action_planning_unassign, action_planning_bulk_move, ..._bulk_assign, ..._bulk_unassign, ..._bulk_publish | Drag, undo and bulk actions. |
get_planning_dashboard | Dashboard cards, KPIs and charts. |
_planning_publish, _planning_publishable, _planning_take, _planning_release, _planning_eligibility_issues, _planning_extra_issues, _planning_daily_load, _planning_work_intervals, _planning_spread_hours, _planning_split, _planning_duplicate_on, _planning_broadcast_open_shift, _cron_send_reminders | Internal building blocks and cron entry points. |
read_group | Names the empty resource group "Open Shift". |
Context keys.
| Key | Effect |
|---|---|
planning_skip_recurrence | create/write do not create, update or propagate to a series. |
planning_no_publication_warning | A write on a published shift does not set publication_warning or request approval. |
planning_keep_role | Role is kept when the resource changes. |
planning_from_dialog | Notifications close the dialog that launched them. |
planning_domain | The schedule's current filter, passed to wizards. |
planning_employee_id | The employee being mailed, read by the email templates. |
planning_tz | Browser time zone sent by the schedule. |
Role: smarterp.planning.role#
Order sequence, name. Fields: name (translatable, required), sequence, active, code, color (default random 1-11), description, company_id (empty means shared), resource_ids (Many2many resource.resource through smarterp_planning_role_resource_rel), resource_count, shift_count, currency_id, hourly_cost (Monetary), slot_properties_definition (PropertiesDefinition). SQL name_company_unique. Constraint: hourly_cost not negative. Method action_view_shifts.
Template: smarterp.planning.template#
Order sequence, start_time, id. Fields: active, sequence, name (stored computed, read only), role_id, company_id, start_time (Float hour, 0 to 24), duration (Float, above zero), note, break_time. SQL: start_time_in_day, break_time_positive, duration_positive. Constraint: duration at most 168. Method _get_datetimes(day, tz).
Recurrence: smarterp.planning.recurrency#
Fields: slot_ids, repeat_interval (at least 1), repeat_unit, repeat_type, repeat_until, repeat_number, last_generated_end_datetime, company_id. Constraint _check_repeat_limits. Methods _repeat_slot, _delete_slots_from, _cron_schedule_next (cron), _gc_empty_recurrences (autovacuum).
Sent schedule: smarterp.planning.planning#
Fields: name, start_datetime, end_datetime, resource_ids, include_unassigned, note, access_token (UUID, unique, read only), company_id. Methods _get_employee_url, _get_employee_shifts, _get_open_shifts, _send_to_employees. It has no menu or view.
Utilisation: smarterp.planning.capacity#
One row per resource and day (unique(resource_id, date)), read only. Fields: date, resource_id, resource_type, user_id, department_id, role_id (default role), company_id, available_hours, allocated_hours, forecast_hours, planned_hours, utilisation, overtime_hours, idle_hours, load_level (idle, busy, full, over). Methods _refresh(resources, date_from, date_to), _cron_rebuild, _mark_dirty, _flush_dirty, _level_for, and a read_group that recomputes utilisation from summed hours. Window: 62 days back, 184 ahead, batches of 50.
Broadcast log: smarterp.planning.broadcast#
Who was told about which open shift. Fields shift_id, resource_id, company_id. Autovacuum deletes rows older than 30 days.
Wizards (transient models)#
| Model | Fields | Entry point |
|---|---|---|
smarterp.planning.send | date_start, date_end, resource_ids, include_unassigned, note, shift_count, role_mismatch_count, company_id | action_send |
smarterp.planning.period.wizard | operation (copy_previous_week, auto_plan; plan_orders with Sales), date_start, date_end | action_confirm |
smarterp.planning.template.apply | template_id, role_id, date_start, date_end, mon..sun, resource_ids, publish, preview_count, preview_skipped, preview_text | action_apply |
smarterp.planning.spread | name, source_model, source_id, company_id, role_id, resource_ids, date_start, deadline, total_hours, hours_per_day, publish, preview_html, warning; with bridges project_id, task_id, sale_line_id | action_plan |
smarterp.planning.duplicate | shift_id, mode, date_start, date_end, weekdays_only, resource_id | action_duplicate |
smarterp.planning.split | shift_id, shift_start, shift_end, split_datetime, open_second | action_split |
smarterp.planning.print | date_start, include_drafts, company_id, domain | action_print (report action_report_planning_rota) |
Extensions of core models#
| Model | Added by | Fields and methods |
|---|---|---|
resource.resource | Core | planning_role_ids, default_planning_role_id, planning_shift_ids; keeps the default role inside the roles. |
hr.employee | Core | default_planning_role_id, planning_role_ids (related to the resource), planning_token, planning_shift_count, _planning_ensure_token, action_view_planning_shifts. |
res.company | Core | The company options in Configuration. |
res.config.settings | Core and bridges | Related fields for the options. |
digest.digest | Core | kpi_planning_open_shifts, kpi_planning_hours and their values. |
resource.calendar.leaves | Core | Marks utilisation dirty when time off changes. |
Bridge models and fields#
| Module | Model | Additions |
|---|---|---|
| Skills | smarterp.planning.skill.requirement (new) | shift_id, template_id, skill_type_id, skill_id, min_level_id, company_id; _label, _missing_for(employee). |
| Skills | smarterp.planning.shift; smarterp.planning.template | skill_requirement_ids; on shifts also missing_skill_warning, has_missing_skill, resource_skill_id. |
| Time Off | smarterp.planning.shift; hr.leave | leave_warning, is_absent; _validate_leave_request posts notes. |
| Contracts | smarterp.planning.shift | contract_warning, is_outside_contract. |
| Attendances | smarterp.planning.shift; hr.attendance; res.company | attendance_check_in, attendance_check_out, attended_hours, late_minutes, left_early_minutes, extra_hours, is_no_show, is_late, attendance_alert_sent; company options; hr.attendance create/write/unlink refresh shifts. |
| Project | smarterp.planning.shift; smarterp.planning.template; smarterp.planning.spread; project.project; project.task | project_id, task_id; project figures planning_shift_count, planning_allocated_hours, planning_open_hours, planning_hours_to_plan; task fields planning_shift_ids, planning_role_id, planning_shift_count, planning_hours_planned, planning_hours_open, planning_hours_to_plan; action_view_planning, action_planning_plan_task, get_panel_data for the overview. |
| Sales | smarterp.planning.shift; smarterp.planning.role; product.template; sale.order; sale.order.line; smarterp.planning.period.wizard; smarterp.planning.spread | sale_line_id, sale_order_id, partner_id, sale_order_state, sale_planning_warning; planning_enabled, planning_role_id on products; planning_shift_count on orders; planning_hours_sold, ..._planned, ..._to_plan, ..._scheduled, ..._done on lines; role product_ids. |
| Timesheets | smarterp.planning.shift; account.analytic.line; project.project; res.company | timesheet_ids, effective_hours, percentage_hours, effective_variance, actual_cost, timesheet_draft_generated; on lines planning_shift_id, planning_state, planning_proposed_hours; planning_timesheet_draft on projects and the company; planning_timesheet_draft_days. |
| SMS | res.company | planning_reminder_sms. |