# RuangJadwal User Guide

Official guide for Curriculum Teams and Curriculum Administrators

Prepared on: July 10, 2026  
Application: RuangJadwal, a native web application for constraint-based lesson timetabling  
Scope: school registration, account activation, staged data entry, Dapodik import, academic master data, timetable generation, exports, backup, restore, and operational troubleshooting

---

## 1. Executive Summary

RuangJadwal helps curriculum teams build auditable lesson timetable drafts. The application separates Dapodik source snapshots, school-managed academic master data, availability rules, learning demand, timetable versions, solver runs, and validation results. This separation allows every change to be traced and prevents a timetable draft from being treated as usable before it passes hard-constraint validation.

The recommended workflow is:

1. Register the school from the public landing page and choose a subscription category.
2. Wait for the school request to be verified and activated through the service activation workflow.
3. Sign in and configure the school profile, team accounts, school logo, and subscription settings if required.
4. Import the five Dapodik files or enter academic master data manually through the XLSX templates.
5. Review Teachers, Subjects, Days and JP Slots, Classes and Rooms, and Teaching Load.
6. Open Schedule Studio, read the preflight report, and resolve every blocker.
7. Generate an automatic timetable draft, review the result, make validated manual adjustments if needed, and submit the draft for review.
8. Export the timetable as XLSX, DOCX, Markdown, JPG, or print it to PDF from the browser.
9. Perform regular backups and use restore only with validated files.

A `Feasible` status means that all hard constraints modeled by the application have been satisfied according to the independent validator. It does not mean that the timetable is pedagogically optimal or officially approved for publication without school policy verification and authorized human approval.

## 2. Operating Principles

### 2.1 Data Sources

RuangJadwal supports two operational data sources.

| Source | Use | Notes |
|---|---|---|
| Dapodik | Initial teachers, subjects, rooms, classes, teaching assignments, and learning demand. | Only recognized file names are processed. Uploaded files are treated as untrusted until server validation succeeds. |
| Manual input or XLSX | Completing, correcting, or building data without a Dapodik snapshot. | Always use the latest template downloaded from the application. |

### 2.2 Recommended Data Sequence

Use this order to detect problems early.

1. Accounts and School.
2. Dapodik Import, if available.
3. Teachers and Teaching Availability.
4. Subjects, Subject per Grade, and Teacher Assignments.
5. Days and JP Slots.
6. Classes and Rooms.
7. Teaching Load.
8. Schedule Studio.
9. Export, backup, and archival.

### 2.3 Hard and Soft Constraints

Hard constraints determine whether a timetable is valid. Examples include: a teacher must not teach two classes at the same slot, a class must not receive two lessons at the same slot, a room must not be double-booked, and each learning demand must receive exactly its required weekly JP.

Soft constraints determine quality. Examples include reducing teacher idle periods, balancing workload, respecting morning preferences, or reducing room moves. A timetable may be feasible when hard constraints are zero, but its quality still requires human review.

### 2.4 Important Boundaries

The application does not invent regional calendars, school curriculum documents, assignment decrees, special facility capacity, cross-class student groups, or local policy rules that have not been entered as data. If such rules matter, the curriculum team must enter them as structured data or treat them as manual verification items before using the timetable.

All times use the 24-hour `HH:mm` format, for example `07:30` and `13:30`. AM/PM input is rejected by server validation.

### 2.5 Common Application Controls

RuangJadwal uses the same control patterns across most internal pages.

| Control | Function | Recommended Use |
|---|---|---|
| **Guide** | Opens contextual help for the current page, tab, table filter, or Schedule Studio view. | Use it when you need the correct sequence, data meaning, checks before continuing, or recovery steps. The `?` shortcut opens the guide, and `Esc` closes it. |
| **Refresh** | Reloads the current page data. | Use it after import, restore, bulk changes, or when several team members work together. The `R` shortcut is available when focus is not inside an input. |
| Sidebar menu button | Shows or hides the sidebar. | Use the menu button or `Alt+B`. On small screens, press `Esc` to close the sidebar. |
| Tabs | Switch between data groups on the same page. | Use tab buttons; with keyboard focus on a tab, left/right arrows move between tabs. |
| Toasts and alerts | Show save results, validation errors, or process status. | Do not continue to the next step until success or error messages are understood. |
| Confirmation dialogs | Protect risky actions such as delete, bulk delete, or restore. | Read the title, details, and confirmation phrase before approving. |

If a page shows an error, the failed change should not be treated as saved. Repair the input, save again, and press **Refresh** to confirm that the display matches server data.

### 2.6 Managed Table Pattern

Master tables such as Teachers, Subjects, Classes, Rooms, Teaching Load, and Availability Rules provide search, filters, sorting, row count, pagination, and row actions.

| Element | Meaning |
|---|---|
| Search | Finds code, name, or other important attributes. |
| Status | Shows all, active, or inactive records. |
| Source | Separates Dapodik data from manual data. |
| Special filter | Finds specific conditions such as missing capacity, positive JP, historical scheduling, or grade-scoped assignments. |
| Sorting | Sorts columns with arrow icons. |
| Rows per page | Selects 10, 25, 50, or 100 rows. |
| Edit action | Updates data with optimistic locking. If another session has changed the row, the save may be rejected to prevent overwriting newer data. |
| Deactivate action | Removes data from active choices without deleting history. |
| Delete action | Deletes eligible data or marks historical data as deleted according to server rules. |

The `DAPODIK` tag means the record came from Dapodik synchronization. The `MANUAL` tag means it was created or updated through the application or a template. Do not delete Dapodik-derived data merely for a small correction; deactivation or an operational field correction is usually safer.

### 2.7 Academic Master XLSX Templates

In addition to Dapodik JSON import, several pages provide **XLSX Template** and **XLSX Import** for bulk entry. Always download the latest template from the relevant page because sheet structure follows the active schema.

| Page | Template | Main Content |
|---|---|---|
| Teachers and Teaching Load | GTK Teachers and Teaching Load | Teachers, basic workload, and learning demand. |
| Subjects | Subjects and Subjects per Grade | Subject catalog, grade variants, curriculum, status, and JP. |
| Days and JP Slots | Days and JP Slots | Active days, day order, JP slots, start time, end time, and slot type. |
| Classes and Rooms | Classes and Rooms | Class groups, grade, curriculum, homeroom, room type, and capacity. |

XLSX import rules:

1. Upload one `.xlsx` file.
2. Maximum file size is 8 MB.
3. Do not change sheet names, headers, or main data types in the template.
4. Import is atomic; if one row fails, the whole file is rejected.
5. After success, open Dashboard and Schedule Studio to check the impact on preflight.

### 2.8 Inactive, Deleted, and Historical Data

RuangJadwal distinguishes active data, inactive data, and historical data marked as deleted. This matters because older timetables, audit records, and exports may still reference the data.

1. Use **Deactivate** when data should no longer be used but still needs to be kept.
2. Use **Delete** only when the application allows it and the impact is understood.
3. Use **Delete all** on Subjects per Grade, Teacher Assignments, or Teaching Load only after creating a backup.
4. Data that has been used by a timetable may be archived or marked as deleted rather than physically removed.
5. Calendar, demand, assignment, or availability changes may make older timetable versions `stale`.

### 2.9 Risk Preview When Editing Data

For data that affects feasibility, especially **Availability Rules** and **Teaching Load**, the application may show a risk preview. This panel helps the team see whether a change will narrow the timetable candidate space.

Use the risk preview as follows:

1. Read the score and risk level.
2. Review root causes, such as a teacher being too restricted, workload being too dense, or a day having too few candidates.
3. Follow safer day/time suggestions when available.
4. Do not save a `deny` rule that closes every candidate for a teacher.
5. After saving, open **Schedule Studio** and press **Refresh status**.

## 3. User Roles

| Role | Main Permissions | Limits |
|---|---|---|
| Curriculum Administrator | Manage the operational data of the user's school, team accounts, school logo, imports, backups, restores, academic master data, schedules, and category-change requests. | Cannot activate other schools, manage the global service catalog, or directly change certain subscription states when review is required. |
| Curriculum Team Member | Assist with academic data, checks, exports, and operational work according to granted access. | Access may be limited by the Curriculum Administrator and school policy. |

## 4. Registering a New School

### 4.1 Opening the Registration Form

1. Open the RuangJadwal landing page.
2. Go to the new school registration section.
3. Confirm that at least one subscription category is available. If no active category is available, registration cannot be submitted.

### 4.2 Completing the School Profile

Fill in the following fields carefully.

| Field | Description | General Validation |
|---|---|---|
| School name | The official school name. | Required. |
| NPSN | Indonesian national school identifier. | Optional, but must match the accepted pattern when filled. |
| Address | Operational school address. | Recommended for document identity. |
| Contact | Phone, email, or administrative contact. | Recommended for verification. |

### 4.3 Choosing a Subscription Category

Choose the category that fits the school's intended use. Categories may be free, generate-quota based, monthly, annual, lifetime, or custom depending on the service catalog available on the registration page. The selected category is recorded with the school request and can later be changed through the review workflow.

### 4.4 Creating the First Curriculum Administrator

Enter the administrator's name, username, email, password, and password confirmation. The password must contain at least 10 characters. The school and initial administrator remain inactive until the registration request is activated.

### 4.5 After Submitting the Request

The application shows a notice that the registration has been received and is waiting for activation. If sign-in is rejected with an activation message, the account exists but the school has not yet been activated.

## 5. School Activation Status

After registration is submitted, Curriculum Administrators and Curriculum Team Members do not need to enter internal application data until the school is active. Use this section to understand the registration status from the school's point of view.

1. Keep the first Curriculum Administrator username and password secure.
2. Watch the notice shown on the sign-in page.
3. If sign-in is rejected with an activation message, the account exists but the school has not yet been activated.
4. Use the official support channel if the school needs confirmation of activation status.

After activation is complete, the first Curriculum Administrator can sign in with the username and password created during registration.

## 6. Signing In

1. Open the landing page.
2. Select **Sign in**.
3. Enter the username and password.
4. Submit the form.

If the session is active, the internal workspace appears. If the session expires while the application calls an API, the page reloads so the user can sign in again.

## 7. Dashboard

The **Dashboard** is the initial control center. Use it to understand whether the data is ready before building a timetable draft.

### 7.1 Main Indicators

| Indicator | Meaning |
|---|---|
| Schedulable teachers | The number of active teachers eligible for scheduling. |
| Schedulable classes | The number of active class groups eligible for scheduling. |
| Weekly teaching load | Total JP from active learning demand. |
| Calendar capacity | Total active teaching slots across active days. |
| Scheduling readiness | Blockers and warnings from the preflight report. |
| Dapodik snapshot | Latest imported snapshot and its use. |
| Latest solver activity | Recent generation runs and their status. |

### 7.2 Recommended Action

If blockers exist, do not start the generator. Follow the corrective messages, repair the related data, and press **Refresh**. Once blockers are zero, open **Schedule Studio**.

## 8. Accounts and School

The **Accounts and School** page contains access management, school profile, subscription category, school logo, backup, and restore settings depending on the user's role.

### 8.1 Access Tab

This tab shows the active session, active school identity, Curriculum Team user list, and backup/restore panel.

#### Managing Curriculum Team Accounts

1. Open **Accounts and School**.
2. In **Curriculum team accounts**, fill in username, display name, email, role, active status, and password if creating a new account.
3. Choose either `Curriculum Administrator` or `Curriculum Team`.
4. Save the account.

When editing an existing user, leave the password blank if it should not be changed.

#### Uploading the School Logo

Curriculum Administrators, or Curriculum Team Members with granted access, can upload a school logo. The logo is used in print headers, official documents, and exports. Use PNG or JPG up to 2 MB.

### 8.2 Subscription Tab

This tab is used to view the school's subscription category and submit a category-change request when the feature is available. Curriculum Administrators and Curriculum Team Members do not manage the global service catalog.

A category includes code, name, summary, billing type, price, currency, schedule-generate quota, feature list, public visibility, recommendation status, and active status.

Important rules for schools:

1. Only active and public categories appear in public registration.
2. A recommended category is shown as the suggested option when available.
3. Free and generate-quota categories have a schedule-generate quota.
4. Category-change requests are recorded and reviewed transactionally.
5. Category changes do not alter timetable data, academic master data, or exported files already created.

#### Requesting a Category Change

Curriculum Administrators can request a category change from the **Subscription** tab.

1. Open **Accounts and School**.
2. Select the **Subscription** tab.
3. Check the school's active category at the top.
4. Choose the target category.
5. Write a clear reason, such as additional generation needs, usage period, or operational support.
6. Press **Submit request**.

While one request is pending, a new request is disabled. The Curriculum Administrator can cancel a pending request. Curriculum Team Members can view status and history, but cannot submit category-change requests.

### 8.3 Operational Backup and Restore

The action buttons at the top of the page provide:

| Button | Function |
|---|---|
| Backup XLSX | Downloads an operational school backup. The backup does not reveal passwords. |
| Restore Template | Downloads a restore template aligned with the active schema. |
| Restore XLSX | Uploads a backup or completed template. |

Restore is atomic. If one row fails validation, the whole restore is rejected. Use the latest backup file and do not change sheet structures outside the documented template.

Restore processes schools, accounts, classes, rooms, subjects, teachers, teacher assignments, teaching load, days, JP slots, teacher availability, timetable versions, and timetable entries according to access rights. Restored timetables are stored as validated drafts. Old passwords are never shown again; new accounts in a restore file must include an initial password.

## 9. Dapodik Import

The **Dapodik Import** page turns a Dapodik snapshot into academic master data.

### 9.1 Required Files

Upload exactly these five files.

| File Name | General Content |
|---|---|
| `dapodik_GTK.json` | Educators and education personnel. |
| `dapodik_Sekolah.json` | School identity in the snapshot. |
| `dapodik_pesertaDidik.json` | Learners and class membership. |
| `dapodik_prasarana.json` | Rooms, buildings, land, and facilities. |
| `dapodik_rombel.json` | Class groups and learning records. |

File names must match exactly. The application rejects duplicate files, unknown files, oversized files, invalid JSON, and JSON envelopes that do not match the Dapodik contract.

### 9.2 Import Procedure

1. Open **Dapodik Import**.
2. Drag the five files into the upload area or press **Choose files**.
3. Make sure all files are marked ready.
4. Press **Validate and import package**.
5. Wait until the server validates, stores the snapshot, and synchronizes master data.

The import runs in one transaction. If it fails, partial data is not accepted.

### 9.3 Synchronizing the Latest Snapshot

If a snapshot already exists, **Synchronize this snapshot** reruns master synchronization from the latest complete import run owned by the school.

Before sync-dapodik runs, the application shows the consequences of synchronization and requires the operator to type an approval statement. Synchronization can update teachers, subjects, rooms, classes, assignments, grade-level JP rules, and teaching demand from the latest Dapodik snapshot. After synchronization, rerun the readiness summary or preflight before creating a new schedule draft.

This page also shows **Dapodik synchronization history**. The history records the action time, action type, source snapshot, and result summary so operators can trace when academic master data was last synchronized. Cleanup must start from a selected synchronization history row/date.

Choose **Review** on a synchronization history row to preview data still tied to that synchronization date. The **Clean selected synchronization effects** button only removes application data from that selected history item, such as Dapodik-based schedule versions, teaching demand, teacher assignments, grade-level rules, and source-backed academic master data. Raw `dapodik_*` snapshots and audit records are retained. If manual data still depends on the targeted Dapodik master data, cleanup is blocked until those dependencies are moved or removed.

### 9.4 Synchronization Results

Synchronization creates or updates:

1. Eligible teachers.
2. Subjects.
3. Subjects per grade.
4. Rooms.
5. Eligible classes.
6. Teacher assignments.
7. Teaching demand.
8. Synchronization audit.

Only GTK records identified as teachers and class groups identified as regular classes are used for active scheduling. Other records remain preserved for lineage but are not scheduled unless the school model later supports them.

### 9.5 When to Reimport, Synchronize, or Use Manual Templates

Use the following choices to keep data consistent.

| Condition | Action |
|---|---|
| The school has a complete new Dapodik package | Reimport the five JSON files. |
| The latest snapshot is correct but master data must be rebuilt | Press **Synchronize this snapshot**. |
| Only operational school data needs correction | Use application forms or academic master XLSX templates. |
| Data does not come from Dapodik | Enter it manually through forms or XLSX templates. |
| A major change is made before generation | Create a backup, import or synchronize, then read Dashboard and Schedule Studio. |

Do not mix old and new Dapodik files in one package. All five files must come from the same snapshot so teacher, class group, room, and learning relationships remain consistent.

## 10. Teachers and Teaching Availability

The **Teachers** page has two tabs: **GTK and load** and **Availability rules**.

### 10.1 GTK and Load

The table shows active teachers, teacher code, appointment date, minimum weekly JP, status, data source, search, filters, sorting, and server-side pagination.

Key fields:

| Field | Function |
|---|---|
| Teacher code | Application identifier. Dapodik-based teachers use a seniority-aware code. |
| Name | Teacher name. |
| Appointment | Appointment date used for ordering. |
| Minimum weekly JP | Expected weekly teaching load. |
| Maximum daily JP | Daily teaching limit. |
| Maximum weekly JP | Weekly upper limit when configured. |
| Available by default | Determines availability before detailed rules are applied. |
| Status | Active or inactive. |

### 10.2 Availability Rules

Availability rules define when a teacher may or may not teach.

| Scope | Meaning |
|---|---|
| All days and times | Applies to the entire scheduling horizon. |
| Full specific day | Applies to one day. |
| Time range across all days | Applies to the same time range on every day. |
| Time range on a specific day | Applies to a time range on one day. |

The effect is either **Allow teaching** or **Deny / unavailable**. More specific rules take priority. At the same specificity level, `deny` overrides `allow`. Explicit per-slot decisions have the highest priority.

### 10.3 Common Risks

Problems often occur when a teacher is unavailable by default but has no `allow` rule, or when too many `deny` rules close all placement candidates. If Schedule Studio shows availability blockers, open this tab and repair the affected rules.

### 10.4 Safe Practice for Availability Rules

Use these patterns to keep availability easy to reason about.

1. If most teachers are generally available, keep **Available by default** enabled and add `deny` rules for unavailable times.
2. If a teacher can teach only on certain days, disable **Available by default** and add `allow` rules for allowed days or times.
3. Avoid `deny all` unless the teacher truly should not be scheduled.
4. After adding a rule, read the risk preview and safer day/time suggestions.
5. Confirm that the teacher's minimum JP remains realistic against remaining availability windows.

### 10.5 Bulk Teacher Entry

To update many teachers, use the **XLSX Template** on the Teachers page. The same template can also contain teaching load. After a successful import, check:

1. number of new and updated teachers;
2. inactive teachers;
3. minimum and maximum JP;
4. available-by-default status;
5. impact on Schedule Studio preflight.

## 11. Subjects

The **Subjects** page has three tabs: **Subjects**, **Subjects per grade**, and **Teacher assignments**.

### 11.1 Subject Catalog

The subject catalog stores code, name, category, color, default block size, and maximum consecutive JP. The catalog is global within the school. Grade-specific curriculum rules are stored separately.

### 11.2 Subjects per Grade

This tab defines curriculum status and weekly JP for a combination of subject, grade, curriculum, and status.

Example:

| Subject | Grade | Curriculum | Status | JP |
|---|---|---|---|---:|
| Mathematics | X | Merdeka Curriculum | Required | 4 |
| Mathematics | XI | Merdeka Curriculum | Required | 5 |

The same subject can have different rules at different grades. Use **Add** to open the variant planner and save multiple combinations atomically.

### 11.3 Teacher Assignments

Teacher assignments connect teachers with subjects and optional grade or curriculum scopes. An empty scope means all grades or all curricula. Dapodik-derived assignments are usually grade-scoped to avoid overly broad eligibility.

Key fields:

| Field | Function |
|---|---|
| Teacher | Assigned teacher. |
| Marker | A-Z marker to distinguish assignments. |
| Subject | Subject taught. |
| Grade scope | Empty for all grades or a specific grade. |
| Curriculum scope | Empty for all curricula or a specific curriculum. |
| Priority | Preference value from 1 to 10. |
| JP limit | Optional maximum JP for the assignment. |

### 11.4 Subject Completeness Check

Before creating teaching load, make sure the three data layers match.

1. The subject catalog has correct codes and names.
2. Subjects per grade have grade, curriculum, status, weekly JP, block size, and maximum consecutive JP.
3. Teacher assignments connect teachers to subjects with the correct grade/curriculum scope.

If the teaching-load add flow does not show the expected teacher or class, the issue is usually in Teacher Assignments or Subjects per Grade. Use filters such as **Grade scoped**, **All grades**, **Scheduled**, and **Never scheduled** to find data that needs repair.

### 11.5 Available Bulk Delete

On **Subjects per Grade** and **Teacher Assignments**, **Delete all** is available for cleanup. Data that has never been scheduled may be physically deleted, while historical data is kept with deleted status. Create a backup first and rerun preflight afterward.

## 12. Days and JP Slots

The **Days and JP Slots** page defines the scheduling time horizon.

### 12.1 Active Days

Each day has a code, name, order, and active status. Order controls display and processing. Inactive days are not used by the solver.

### 12.2 JP Slots

Each slot has:

| Field | Function |
|---|---|
| Day | Owning day. |
| JP position | Slot order within the day. |
| Label | Slot label, for example JP 1 or Break. |
| Start | Start time in `HH:mm`. |
| End | End time in `HH:mm`. |
| Type | `Teaching`, `Break`, or `Fixed event`. |
| Status | Active or inactive. |

Only **Teaching** slots can host learning sessions. **Break** and **Fixed event** slots appear in the grid but are not solver slots.

### 12.3 Recommended Practice

1. Ensure every active day has the correct teaching slots.
2. Do not use break slots as teaching slots to create artificial capacity.
3. Rerun preflight after calendar changes because older timetable versions may become stale.
4. Use the calendar XLSX template for bulk entry.

### 12.4 Slot Defaults and Calendar Deletion

When adding a new slot, the application helps fill the next position. If a day has no slots yet, the default position is `1`. If the day already has slots, the default position follows the next sequence and the default start time uses the previous slot's end time. These values still must be checked before saving.

Calendar deletion actions:

1. **Delete slot** removes one slot from the active calendar when allowed.
2. **Delete all slots for this day** clears slots on one day.
3. **Delete all days** clears active days and related slots.

If a slot has timetable history, the server may archive references so older versions can still be read. After calendar changes, do not use an older draft until version validation shows zero blockers.

## 13. Classes and Rooms

The **Classes and Rooms** page has **Classes** and **Rooms** tabs.

### 13.1 Classes

Class fields include code, name, grade, curriculum, student count, homeroom, scheduling eligibility, and active status. Only active classes marked as schedulable are used by the solver.

### 13.2 Rooms

Room fields include code, name, room type, capacity, and active status. Room capacity is used by validation when available. If capacity is missing, the application may warn that room-capacity validation is not fully proven.

### 13.3 Common Risks

1. A class has no grade or curriculum matching the subject-per-grade rules.
2. Homeroom is missing, so teaching demand cannot automatically inherit a room.
3. Room capacity is blank for many demands, making capacity validation incomplete.

### 13.4 Accurate Class and Room Practice

Use the following guidance.

1. Fill class grade with the same code used in Subjects per Grade.
2. Fill class curriculum when the school differentiates curriculum between class groups.
3. Enable **Schedulable** only for classes that truly appear in the lesson timetable.
4. Fill homeroom so teaching load can inherit a default room.
5. Fill room capacity when class capacity is a school constraint.
6. Use **Schedulable classes** and **Non-class groups** filters to separate regular classes from reference data.

## 14. Teaching Load

The **Teaching Load** page defines the learning demand that must be placed into the timetable.

### 14.1 Main Fields

| Field | Function |
|---|---|
| Class | Target class. |
| Subject | Subject to schedule. |
| Teacher | Assigned teacher. |
| Room | Default room, if any. |
| Weekly JP | Required JP per week. |
| Block size | Default session duration. |
| Maximum JP per day | Daily limit for that subject in that class. |
| Status | Active or inactive. |

### 14.2 Teaching Load Planner

The **Add** button opens the demand planner. The workflow is:

1. Choose a teacher with active assignments.
2. Choose a subject taught by that teacher.
3. Select classes matching the assignment grade and curriculum scope.
4. Select the subject-per-grade variant if more than one exists.
5. Fill in maximum JP per day when needed.
6. Save all demand entries.

The system rejects duplicate class-subject demand, teachers without active assignments, and classes without matching subject-per-grade rules.

### 14.3 Weekly JP Session Patterns

RuangJadwal uses these session patterns.

| Weekly JP | Session Pattern |
|---:|---|
| 1 | One 1-JP session |
| 2 | One 2-JP session |
| 3 | One 3-JP session |
| 4 | Two 2+2 sessions on different days |
| 5 | Two 3+2 or 2+3 sessions on different days |

Breaks do not split a pedagogical meeting. The display may show a break label, but the solver reads the sequence through teaching slots.

### 14.4 Teaching Load Risk Preview

When adding or editing teaching load, the application may calculate feasibility risk. Read the panel before saving, especially when:

1. weekly JP is large;
2. teacher availability is narrow;
3. the class already uses almost all slots;
4. the subject must be split into multiple sessions;
5. special rooms or homerooms are limited.

If risk is high, repair the input before generation: widen teacher availability, check alternative assignments, add time capacity if school policy allows it, or reduce overly strict daily limits.

### 14.5 Bulk Delete Teaching Load

**Delete all** on Teaching Load deletes demand that has never been scheduled and marks historical demand as deleted. Use it only when rebuilding demand from Dapodik or a template. Safe order:

1. Create a backup XLSX.
2. Delete all teaching load only when required.
3. Reimport or recreate the demand.
4. Check total JP on Dashboard.
5. Run preflight in Schedule Studio.

## 15. Pre-Generation Checks

Before generating a timetable, confirm that:

1. At least one active day exists.
2. Active teaching slots exist.
3. Active eligible teachers exist.
4. Active eligible classes exist.
5. Subjects per grade match the classes.
6. Teacher assignments match subjects, grades, and curricula.
7. Active teaching demand has positive weekly JP.
8. Class weekly demand does not exceed teaching-slot capacity.
9. Teacher availability does not close every candidate.
10. Special room or capacity policies have been entered when they are required by the school.

If Schedule Studio shows `0 blockers`, the modeled hard-constraint gate has passed. If warnings remain, read them and decide whether they must be resolved before the draft is used.

### 15.1 Reading Studio Diagnosis

Schedule Studio shows several diagnosis panels. Read them in this order.

1. **Readiness banner**: determines whether the generator is enabled or locked.
2. **Infeasibility sources**: shows teachers, classes, days, times, or demand closing the candidate space.
3. **Feasibility risk map**: shows the densest areas even when they are not blockers yet.
4. **Teacher availability risk**: shows teachers whose availability is most risky against demand.
5. **Availability proof**: appears when blockers exist and helps identify closed time windows.
6. **Constraints**: opens a summary of active constraints checked by the application.

Prioritize blockers before warnings. If a panel gives an action such as opening Teachers, Classes, or Teaching Load, repair the data there, return to Studio, and press **Refresh status**.

## 16. Schedule Studio

Schedule Studio is used to generate, inspect, revise, and export timetables.

### 16.1 Main Components

| Component | Function |
|---|---|
| Demand metrics | Weekly JP, demand count, and session count. |
| Calendar metrics | Active slot and day count. |
| Resource metrics | Eligible teacher and class count. |
| Readiness | Blockers and warnings. |
| Timetable versions | Draft, review, published, or archived versions. |
| Recent processes | Generate history with status, engine, seed, runtime, and diagnosis. |
| Timetable grid | Class, teacher, subject, or room view. |
| Version validation | Fingerprint, occupancy, and hard-constraint checks for the active version. |

### 16.2 Generation Statuses

| Status | Meaning | Action |
|---|---|---|
| `validating` | The server is checking input. | Wait. |
| `running` | The schedule-construction engine is searching. | Wait and monitor progress. |
| `feasible` | A complete draft was found and the independent validator found no blockers. | Review quality and school policy. |
| `infeasible` | Preflight or the solver proved a conflict under active hard constraints. | Repair the data according to the diagnosis. |
| `unknown` | The search limit expired without a complete solution and without proof of infeasibility. | Increase time if safe, reduce bottlenecks, or repair restrictive data. |
| `failed` | A technical error occurred or post-validation rejected the result. | Read the issue, keep the request ID if shown, and contact the administrator. |

### 16.3 Generating an Automatic Draft

1. Open **Schedule Studio**.
2. Confirm that there are no blockers.
3. Press **Create schedule draft**.
4. Enter version name, academic year, semester, seed, minimum first-solution time, and maximum process time.
5. Submit the dialog.
6. Monitor input validation, candidate construction, solution search, sequence optimization, draft persistence, and final validation.
7. If successful, select the new version and review the grid.

The seed helps reproduce the run. The same input and seed should produce an auditable search process.

#### Time Limits and Search Progress

The generator dialog reads the server runtime limit. **Maximum process time** cannot exceed that limit. **Minimum first-solution time** controls how long the engine waits for an initial solution before stopping and showing pressure diagnosis.

While a run is active, Studio shows these phases:

1. input validation;
2. candidate construction;
3. solution search;
4. sequence optimization;
5. draft persistence;
6. post-validation.

Do not manually reload the page while a run is active unless necessary. Studio refreshes active run status automatically and shows recent processes with seed, runtime, JP count, engine, and diagnosis.

### 16.4 Reading the Timetable Grid

Available views:

| View | Use |
|---|---|
| By class | Review all classes side by side. This is the primary timetable view. |
| By teacher | Review teacher load and idle periods. |
| By subject | Review distribution for one or all subjects. |
| By room | Review room usage, including the virtual `No room` resource. |

Use the **Resource** filter to view all resources or one selected resource.

Grid legend:

| Mark | Meaning |
|---|---|
| Colored block | Learning session. Color follows the subject. |
| Continuation arrow | Continuation slot of a multi-JP session. |
| Break | Break slot shown in the grid but not a solver candidate. |
| School event | Fixed-event slot that cannot receive a learning session. |
| Open slot | Teaching slot that is empty or can be a move target on a draft. |
| 4-JP/5-JP pattern | Marker that the subject has a split weekly session pattern. |

### 16.5 Manual Revision

On a `draft` version, the curriculum team can:

1. Click a session to open the move editor.
2. Drag a session to a legal open slot.
3. Remove a session from the draft.
4. Place remaining sessions manually through **Place session**.

All changes are saved transactionally. The server rejects changes that cause teacher conflicts, class conflicts, room conflicts, availability violations, session-pattern violations, or JP-total violations.

#### Placing Remaining Sessions

**Place session** is enabled when a draft still has unmet demand and no blocker exists except missing JP. The dialog shows:

1. unmet learning demand;
2. scheduled JP and remaining JP;
3. required session pattern, such as `2+2` or `3+2`;
4. selectable target days and slots;
5. next session duration.

Do not change duration merely to force a slot. Duration must follow the displayed session pattern. If placement is rejected, read the validation message and repair the cause instead of repeating the same slot.

### 16.6 Sending a Draft for Review

If version validation has zero blockers, press **Send for review**. The version moves from `draft` to `review`. Non-draft versions are not edited directly. Publication still requires authorized human approval and the publication workflow remains guarded.

### 16.7 Deleting a Generated Draft

A generated version that is not published can be permanently deleted with **Delete permanently**. The application asks for confirmation and atomically removes entries, occupancy rows, and validation issues. Solver runs and process audit records remain preserved.

### 16.8 Stale Versions and Locked Editor

A timetable version may become `stale` when master data changes after generation. Examples include changes to slots, classes, teachers, availability, assignments, or teaching load. If the editor is locked, do not force grid edits. Read **Version validation**, repair the changed data, then create a new draft or use a version that is still consistent.

## 17. Timetable Export

The timetable grid provides:

| Button | Output |
|---|---|
| XLSX | A complete Excel workbook, including class, teacher, room, subject views, assignment audit, and teacher directory according to the export implementation. |
| DOCX | Word document for the active view. |
| Markdown | Markdown file for the active view. |
| JPG | Image generated from the active grid. |
| Print/PDF | Opens the browser print dialog; choose save as PDF if needed. |

Before exporting, choose the view, resource, paper size, and orientation. For official documents, verify the school logo, school name, academic year, semester, and version status.

### 17.1 Recommended Export Order

1. Select a valid timetable version.
2. Confirm that version validation shows `0 blockers`.
3. Choose the view: by class, by teacher, by subject, or by room.
4. Choose a specific resource when a smaller export is needed.
5. Choose paper size: `A4`, `F4/Folio`, `Letter`, or `A3`.
6. Choose landscape or portrait orientation.
7. Run the needed export.
8. Open the exported file and check letterhead, academic year, semester, class/teacher/room, and total JP before distribution.

For curriculum meetings, use XLSX as the primary archive because it contains many audit views. Use DOCX, JPG, or PDF for more concise distribution to specific audiences.

## 18. Backup and Restore

### 18.1 Regular Backup

Create a backup before:

1. Large imports.
2. Restore operations.
3. Bulk teacher, class, slot, or demand changes.
4. Important generation runs.
5. Deleting historical data.

Download backups from **Accounts and School** using **Backup XLSX**.

### 18.2 Restore

1. Download **Restore Template** or use a backup generated by the application.
2. Fill in data according to the sheet structure.
3. Open **Restore XLSX**.
4. Upload one XLSX file.
5. Wait for validation.
6. If successful, recheck Dashboard and Schedule Studio.

Restore does not reveal old passwords. New accounts must include an initial password in the restore file.

### 18.3 Safe Restore Boundaries

Do not restore while other users are editing the same data. Coordinate the work window, create a backup first, and ensure the restore file comes from a trusted source.

### 18.4 After Restore Succeeds

Run these checks.

1. Open **Dashboard** and confirm teacher, class, load, day, and slot counts look reasonable.
2. Open **Accounts and School** to confirm active accounts.
3. Open **Schedule Studio** and read preflight.
4. If timetables were restored, select the version and read **Version validation**.
5. If a version is stale, create a new draft before exporting.
6. Keep the restore file and the pre-restore backup as temporary audit records.

## 19. Troubleshooting

### 19.1 Registration Cannot Be Submitted

Likely causes:

1. No active and public subscription category exists.
2. NPSN, username, or email is already registered.
3. Password and confirmation do not match.
4. Database configuration is unavailable.

Actions:

1. Contact the official support channel so registration categories can be reviewed.
2. Use a different username or email.
3. Recheck the password fields.
4. Contact the administrator if configuration is reported unavailable.

### 19.2 Sign-In Is Rejected

Likely causes:

1. Wrong username or password.
2. School has not been activated.
3. Account is inactive.
4. School has been deactivated.

Actions:

1. Recheck credentials.
2. Contact the school's Curriculum Administrator or the official support channel to confirm activation status.
3. Confirm that the school is active.

### 19.3 Dapodik Import Is Rejected

Likely causes:

1. The upload does not contain exactly five files.
2. File names do not match.
3. A file is larger than 10 MB.
4. Total upload size exceeds 30 MB.
5. A file is not valid JSON.
6. The JSON envelope does not match the Dapodik contract.

Actions:

1. Re-export files from the Dapodik source.
2. Do not rename files.
3. Upload all five files together.
4. If failure repeats, keep the error message and contact the administrator.

### 19.4 Teacher Does Not Appear

Likely causes:

1. GTK is not identified as teacher by `jenis_ptk_id=92` or the teacher label.
2. Teacher is inactive.
3. Teacher was removed from active management.
4. Dapodik snapshot has not been synchronized.

Actions:

1. Review the Teachers tab.
2. Synchronize Dapodik again.
3. Activate the teacher if the teacher should be scheduled.

### 19.5 Class Does Not Appear

Likely causes:

1. The class group is not a regular class.
2. Class is inactive.
3. Class is not marked schedulable.
4. Dapodik data is incomplete.

Actions:

1. Review the Classes tab.
2. Enable **Schedulable** when appropriate.
3. Check grade and curriculum.

### 19.6 Teaching Load Cannot Be Created

Likely causes:

1. Teacher has no assignment.
2. Subject-per-grade rule has not been created.
3. Assignment grade or curriculum does not match the class.
4. Duplicate demand already exists for the class and subject.

Actions:

1. Complete Teacher Assignments.
2. Complete Subjects per Grade.
3. Use the demand planner and read validation messages.

### 19.7 Generator Is Disabled

The generator is disabled when preflight still has blockers. Open the diagnosis panel in Schedule Studio, follow the action links, repair the data, and refresh the Studio.

### 19.8 Generation Status Is `unknown`

`unknown` means the search limit expired without a complete solution and without proof of infeasibility. Possible actions:

1. Increase the time limit when server limits allow.
2. Review teachers with the most restrictive availability.
3. Avoid 100 percent class-capacity saturation if school policy allows extra time capacity.
4. Relax preference-level constraints only with approval from the policy owner.
5. Review remaining demand in the diagnosis.

### 19.9 Timetable Version Is Stale

A version becomes stale when master data, calendar, demand, or availability changes after generation. Generate a new draft or revise from a valid baseline. Do not use stale versions for publication.

### 19.10 Export Problems

If JPG export fails, the grid may be too large for the browser canvas limit. Try selecting one class, teacher, subject, or room first. For PDF, use **Print/PDF** and choose an appropriate paper size.

### 19.11 Restore Is Rejected

Restore is rejected when sheets are missing, headers are changed, references do not match, the file is too large, or a row violates validation. Repair the file, download the latest template, and upload again. No partial changes are accepted when restore fails.

### 19.12 Academic Master XLSX Import Is Rejected

Likely causes:

1. The file is not `.xlsx`.
2. The file is larger than 8 MB.
3. The template came from an older application version.
4. Headers or sheet names were changed.
5. A reference does not match, such as teacher, class, subject, grade, or curriculum code.
6. A duplicate row exists.

Actions:

1. Download the latest template from the same page.
2. Copy old data into the new template without changing headers.
3. Repair rows named in the error message.
4. Upload one file again.

### 19.13 Save Is Rejected Because of Conflict

If data is rejected after being open for a long time, the row may have been changed by another session. Press **Refresh**, reopen the data, reapply the change, and save again. This prevents team members from overwriting one another's work.

### 19.14 Manual Timetable Revision Is Rejected

Likely causes:

1. The target slot is not an active teaching slot.
2. The teacher, class, or room is already occupied.
3. Teacher availability rejects the slot.
4. Duration does not match the session pattern.
5. The version is not `draft` or is already stale.

Actions:

1. Read the validation message.
2. Try another legal slot.
3. Repair availability or load if the message points to master data.
4. If the version is stale, create a new draft.

### 19.15 Category Request Cannot Be Submitted

Likely causes:

1. The user is not a Curriculum Administrator.
2. Another category request is still pending.
3. No active target category exists besides the current category.
4. The reason is blank.

Actions:

1. Review the **Subscription** tab.
2. Cancel an old pending request when it is no longer needed.
3. Write an operational reason that satisfies validation.
4. Contact the official support channel if no category option is available.

## 20. Ready-to-Generate Checklist

Use this checklist before pressing **Create schedule draft**.

- [ ] The school is active and the active school context is correct.
- [ ] Five Dapodik files have been imported or manual master data is complete.
- [ ] Active teachers represent only teachers who should be scheduled.
- [ ] Teacher minimum and maximum workload values have been verified.
- [ ] Teacher availability rules match school policy.
- [ ] Subjects per grade are complete.
- [ ] Teacher assignments match grade and curriculum.
- [ ] Active days and teaching slots are final.
- [ ] Break and fixed-event slots are not used as teaching slots.
- [ ] Eligible classes are correct.
- [ ] Homerooms and room capacity are filled when required.
- [ ] Active teaching demand has positive JP.
- [ ] No demand lacks an eligible teacher.
- [ ] Schedule Studio has no blockers.
- [ ] Warnings have been read and consciously accepted or resolved.
- [ ] XLSX templates used are the latest templates downloaded from the application.
- [ ] Bulk changes have been followed by **Refresh** and a new preflight check.

## 21. Post-Generation Checklist

- [ ] The run status is `feasible`.
- [ ] Version validation has `0 blockers`.
- [ ] Scheduled JP equals required JP.
- [ ] The class view has been reviewed.
- [ ] The teacher view has been reviewed.
- [ ] The room view has been reviewed when rooms are used.
- [ ] The subject view has been reviewed for critical subjects.
- [ ] Idle periods, daily load, and subject distribution have been reviewed.
- [ ] Manual edits, if any, have been revalidated.
- [ ] The version intended for sharing has been sent to review.
- [ ] Exported files have been checked before distribution.
- [ ] The primary XLSX file has been stored as an audit archive.
- [ ] A backup after the final timetable has been created and stored in a restricted location.

## 22. Data Governance and Privacy

1. Do not share Dapodik files, backups, or restore files through insecure channels.
2. Store backup files in restricted locations and name them clearly.
3. Remove local files that are no longer needed after restore or audit.
4. Do not place passwords in notes, screenshots, or guide documents.
5. Use separate accounts for each team member to improve access auditability.
6. Do not delete or deactivate historical data without school backup and approval.
7. Use restore only during an agreed work window so it does not overwrite another team member's work.

## 23. Technical and Policy References

This guide is based on the analysis of RuangJadwal code, schema, services, migrations, internal documentation, and the external references below.

| Reference | Relevance |
|---|---|
| [Kemendikdasmen Dapodik Portal](https://dapo.kemendikdasmen.go.id/) | Official context for Indonesian education data. |
| [Kemendikdasmen Dapodik Downloads](https://dapo.kemendikdasmen.go.id/unduhan) | Official reference for Dapodik application and supporting updates. |
| [OR-Tools CP-SAT Solver](https://developers.google.com/optimization/cp/cp_solver) | Reference for `OPTIMAL`, `FEASIBLE`, and constraint-solver status interpretation. |
| [Permendikdasmen No. 13 of 2025 on BPK](https://peraturan.bpk.go.id/Details/322506/permendikdasmen-no-13-tahun-2025) | Regulation reference that must still be verified against school policy. |
| Internal `README.md`, `STUDIO_JADWAL_ANALYSIS.md`, and `DAPODIK_PEMBELAJARAN.md` | Actual application behavior, validator, solver, and Dapodik synchronization evidence. |

## 24. Closing Note

RuangJadwal works best when the curriculum team treats data as a decision source that must be complete, traceable, and verifiable. Do not chase timetable generation before the base data is correct. A reliable timetable begins with clean academic master data, a realistic calendar, honest teacher availability, and a preflight report that is read carefully.