EducatION Integration (School Management Systems)

The EducatION integration connects ACCELERO to school management systems. Periodically, ACCELERO queries an external API of the academic system and synchronizes, in the local database, students, their guardians (financial and pedagogical), and the people authorized to pick up the students — creating people, companies, and categories automatically. Optionally, the plugin also integrates with TOTVS RM to send the students' attendance control (absence records).

Availability

This integration is provided as a plugin (education) and must be installed and enabled by the IONGRADE technical team. Contact support to check compatibility with your ACCELERO version.

Compatibility

Current plugin version: 1.0.0 — compatible with ACCELERO 2.16.8 or higher.

Relationship with other education plugins

EducatION handles the synchronization of records (students/guardians/authorized people) and attendance from the academic system. For the app features aimed at the school environment, see the Accelero Edu integration. The plugins have distinct scopes and should not be confused.

---

What the integration does

With the plugin active, ACCELERO automatically reflects the academic system's registry: you just configure the API address and the operating parameters so that students and their links are kept synchronized, with no manual registration.

Feature	What happens in ACCELERO
Student synchronization	Each student returned by the API is registered as a person, with name, document, and photo (when provided)
Categories by class	The student is associated with categories whose names correspond to the classes they are enrolled in
Company per student	A company is created whose code/description is the student ID; the student is linked to it
Guardians	Financial and pedagogical guardians are registered, receive configured categories, and are linked to the student's company
Authorized people	People authorized to pick up the student are registered, receive a configured category, and are linked to the student's company
Multiple stages/years	It is possible to synchronize more than one stage/year per run (useful at the turn of the school year)
Attendance control (TOTVS RM)	Compares the day's schedule with the recorded accesses and sends the students' absence records to TOTVS
Integration logs	Every run (synchronization and attendance) is recorded with status and message for auditing

Main benefit

Keeps the registry of students, guardians, and authorized people always aligned with the academic system, eliminating manual registration and the links between them.

---

Configuration

Navigation path: Advanced > System > Plugins - EducatION

The screen has the tabs: API, Settings, Attendance, and Logs. An additional Partial synchronization tab appears only when the development module (dev) is enabled.

API tab

Connection data with the academic system's API.

TODO: Add Screenshot

The API tab of the EducatION configuration screen, showing the Host, Authentication type, Username / Bearer token, API Password, API Timeout, and Integration user fields, plus the Save and Synchronize buttons.

Field	Description
Host	Address of the external API. The year/stage to synchronize can be provided as the placeholder {{year}} in the URL (e.g., https://servidor.com.br/api/alunos/{{year}})
Authentication type	API authentication system: None, Basic auth, or Bearer token
Username / Bearer token	Username (for Basic auth) or the token (for Bearer token)
API Password	Password — used only when the type is Basic auth
API Timeout	Time limit (in seconds) for the API calls
Integration user	ACCELERO operator on whose behalf the data changes made by the integration appear in the system logs

Settings tab

Defines which stages/years to synchronize and the default categories and association types applied to guardians and authorized people.

TODO: Add Screenshot

The Settings tab of EducatION, showing the Stages to synchronize field and the Financial guardians, Pedagogical guardians, and Authorized people blocks, each with Category and Association type.

Field	Description
Stages to synchronize (separate with commas)	One or more stages/years to process. Each value replaces the {{year}} placeholder in the URL. When empty, it uses the current year
Financial guardians — Category	Category assigned to synchronized financial guardians
Financial guardians — Association type	Association type (person-company link) applied to financial guardians
Pedagogical guardians — Category	Category assigned to synchronized pedagogical guardians
Pedagogical guardians — Association type	Association type applied to pedagogical guardians
Authorized people — Category	Category assigned to synchronized authorized people
Authorized people — Association type	Association type applied to authorized people

Student categories

The students' categories are not defined here: the student is automatically associated with categories whose names correspond to their classes (see How data is organized).

Attendance tab

Configures the attendance control integration (absences) with TOTVS RM. This tab is optional and is only used when attendance is enabled.

TODO: Add Screenshot

The Attendance tab of EducatION, showing the Attendance Configuration, Filters, and Time windows fields, the Synchronize attendance button, and the Test / Reprocess a specific date block.

Field	Description
Enable attendance	Turns attendance processing on/off (No / Yes)
Automatic execution time	Time of day (0–23) for the daily automatic processing (default: 3)
TOTVS RM Host	Base URL of the TOTVS RM API
SQL query name	Name of the REST query configured in TOTVS (default: ACCELERO_FREQUEN)
Student categories	Multi-selection of categories used to filter students in the attendance calculation
Entry areas	Multi-selection of areas whose passage is considered an entry
Exit areas	Multi-selection of areas whose passage is considered an exit
Entry from / Entry until	Time window considered for entry (optional)
Exit from / Exit until	Time window considered for exit (optional)

Attendance credentials

The credentials used when sending to TOTVS RM (username and password) are the same ones configured on the API tab.

Time windows

The student is considered present if they register an entry within the entry window or an exit within the exit window. Leave the windows blank to not apply a time filter.

Logs tab

Displays the Integration Logs of the plugin's runs (see Integration Logs).

Screen buttons

Button	Tab	Function
Save	API / Settings / Attendance	Persists the configuration
Synchronize	API	Starts an immediate synchronization of students/guardians/authorized people. The process may take several minutes
Synchronize attendance	Attendance	Processes and sends the previous day's attendance to TOTVS
Test (without sending)	Attendance	Runs the attendance calculation for a specific date in test mode (dry-run), without sending anything to TOTVS
Send to TOTVS	Attendance	Processes and sends the attendance of a specific date to TOTVS

---

How data is organized

Synchronization creates and maintains the following links from the data received from the API:

• Student → registered as a person; receives categories named after each class they are enrolled in; is linked to their own company.
• Student's company → created with a code and description equal to the student ID. It serves to group the student and everyone related to them.
• Financial / pedagogical guardian → registered as a person, receives the configured category and association type, and is linked to the company of the student they are responsible for.
• Authorized person → registered as a person, receives the configured category and association type, and is linked to the student's company.

Identification by metadata

Each synchronized person stores its source identifier (education.id) in the metadata, used to reconcile records between runs and for the attendance calculation.

---

External API format

ACCELERO makes a GET request to the configured URL and expects an HTTP 200 code with a JSON array of objects. The basic structure is the same for students and guardians (id, nome, documento, foto).

Field	Required	Description
id	Yes	Student identifier at the source
nome	Yes	Name (max. 50 characters)
documento	Yes	CPF/RG (max. 50 characters)
foto	No	Photo URL
responsavelPedagogico	No	Object with id, nome, documento, foto
responsavelFinanceiro	No	Object with id, nome, documento, foto
autorizados	No	Array of objects with id, nome, documento, foto
turmas	No	Array with the names of the student's classes

Student in multiple classes

It is possible to send the same student in more than one position of the array to represent enrollment in several classes. The categories corresponding to the classes are created/associated as needed.

TODO: Add Diagram

Diagram of the synchronization flow: external API → ACCELERO (creation of company, categories per class, student's person, guardians and authorized people, and their links).

---

Integration Logs

Navigation path: Advanced > System > Plugins - EducatION > Logs tab

Each run of the plugin is recorded in the integration logs table, allowing you to audit results and diagnose failures.

TODO: Add Screenshot

The Logs tab with the Filter by type filter and the logs table (columns Date, Type, Status, Message, Run).

Filter

Filter	Options
Filter by type	All / User synchronization / Attendance

Columns

Column	Content
Date	Date and time of the record
Type	Type of the run (user synchronization or attendance)
Status	Result of the record: success, error, warning, or info
Message	Description of what happened (e.g., "Synchronization finished. Total: N records processed")
Run	Unique identifier of the run, used to group the records of the same batch

---

Attendance control (TOTVS RM)

When enabled, attendance compares the day's schedule (obtained via REST in TOTVS RM) with the accesses recorded in ACCELERO, identifies the absent students, and sends those records to TOTVS via SOAP.

TODO: Add Diagram

Diagram of the attendance flow: TOTVS RM (REST, schedule) → ACCELERO (queries access logs and calculates absences) → TOTVS RM (SOAP, sending absences).

How it works

1. Fetch the day's schedule in TOTVS RM, using the configured SQL query and the day of the week (Monday to Friday; weekends are not processed).
2. Fetch the day's accesses in ACCELERO, considering only students of the configured categories that have a source identifier (education.id).
3. Detect presence: the student is considered present if they registered an entry (and/or exit) in the configured areas and time windows. Students scheduled in the timetable who are not marked as present are flagged as absent.
4. Send the absences to TOTVS RM, grouped by class.
5. Record the result in the Integration Logs (type Attendance).

Triggering

Method	How
Automatic	Daily, at the time configured in Automatic execution time, processing the previous day
Manual	The Synchronize attendance button (processes the previous day)
By date	The Test (without sending) and Send to TOTVS buttons in the Test / Reprocess a specific date block

Test before sending

Use Test (without sending) to validate the configuration (categories, areas, windows, and connection with TOTVS) for a specific date before sending the real data.

---

Partial synchronization (dev module)

When the development module (dev) is enabled, the Partial synchronization tab lets you paste a partial JSON (an array in the same format as the external API) and process it manually, without querying the API.

Restricted use

Partial synchronization is a technical/diagnostic support tool, available only with the dev module enabled. It is not part of everyday operation.

---

When submissions are triggered

Registry synchronization

• Automatically, in a scheduled run (queue job), reprocessing all configured stages every period.
• Manually, via the Synchronize button on the API tab.

A locking mechanism (semaphore) prevents two synchronizations from running at the same time; if one is already in progress, the new run is interrupted.

Attendance

Triggered automatically at the configured time, or manually via the buttons on the Attendance tab (see Triggering).

---

Use cases

Enable student synchronization

1. Request that IONGRADE install the education plugin.
2. In Advanced > System > Plugins - EducatION, on the API tab, fill in the Host, authentication type, and credentials, and select the Integration user.
3. On the Settings tab, provide the stages to synchronize and define the category and association type for guardians and authorized people.
4. Click Save and then Synchronize for the first load.
5. Track the result on the Logs tab.

Enable attendance control

1. On the Attendance tab, set Enable attendance = Yes.
2. Fill in TOTVS RM Host and SQL query name.
3. Select Student categories, Entry areas, and Exit areas and, if desired, the time windows.
4. Save and use Test (without sending) for a known date, checking the diagnosis.
5. Once validated, leave the automatic execution active (or use Send to TOTVS for specific dates).

Investigate a synchronization with an error

1. Access the Logs tab and filter by User synchronization.
2. Locate the run with the error status and read the Message.
3. Fix the problem at the source (API) or in the configuration and run Synchronize again.

---

Best practices

• Correct stages at the turn of the year: during the school-year transition, provide both stages in Stages to synchronize to keep both periods updated.
• Dedicated categories and associations: create categories and association types specific to guardians and authorized people, avoiding mixing them with other audiences.
• Dedicated integration user: configure a specific ACCELERO user (e.g., "EducatION Integration") as responsible for the changes in the logs.
• Test attendance before sending: always run Test (without sending) when changing areas, windows, or the TOTVS SQL query.
• Track the logs: check the Logs tab after each relevant load to identify records with an error.

---

Troubleshooting

Synchronization does not create/update people

Possible causes:

• External API inaccessible, with incorrect authentication, or returning a code other than 200
• Incomplete configuration (Host, authentication type, integration user, categories/associations)
• A synchronization is already in progress (semaphore lock)

Solution:

1. Check the fields on the API tab (Host, authentication, credentials, timeout).
2. Check the required categories and association types on the Settings tab.
3. See the Logs tab (filter User synchronization) and read the error message.
4. Wait for a running synchronization to finish before starting another.

Attendance does not send absences to TOTVS

Possible causes:

• Attendance disabled
• Incorrect TOTVS RM Host or SQL query name
• Entry/exit areas or student categories not configured
• Students without the source identifier (education.id) — they were not synchronized by the plugin

Solution:

1. Confirm Enable attendance = Yes.
2. Run Test (without sending) for a known date and analyze the diagnosis.
3. Check areas, categories, and time windows.
4. Make sure the students were created by the synchronization (API tab → Synchronize).
5. Consult the Logs tab (filter Attendance).

Attendance prerequisite

The attendance calculation depends on students synchronized by the plugin itself (with education.id in the metadata) and on accesses recorded in the configured areas. Manual records that did not go through the integration are not included in this calculation.

---

Integration with other modules

People and Companies

The integration creates and maintains the registry of People (students, guardians, and authorized people) and of Companies (one per student), plus the links between them.

Categories

Students are associated with categories corresponding to their classes, and guardians/authorized people with the configured categories. See People to understand the use of categories.

Areas and Access logs

Attendance control uses the Areas configured as entry and exit and the recorded accesses — see Logs and Monitoring.

Accelero Edu

For the app features of the school environment, see the Accelero Edu integration — a scope distinct from EducatION.

---

Next Steps

• People — Understand the registry of students, guardians, and authorized people
• Companies — See how the per-student companies are used
• Areas — Configure the entry and exit areas for attendance
• Logs and Monitoring — Understand the accesses used in the attendance calculation
• Accelero Edu — App features for the school environment
• Plugins — Learn more about the ACCELERO plugin system