Skip to main content

General

Optional properties are marked with a question mark (?) at the end of the type. Instead of setting a property to null, the property can also simply be omitted. IDs always need to be URL compatible and therefore must be urlencoded. We recommend to use only unicode letters, numbers and underscores in all IDs. You can get more sample bodies by making a GET request to

https://TODO_FLOW_HOST/import/getSample?entity=TODO_REPLACE_WITH_ENTITY&contentType=TODO_REPLACE_WITH_CONTENT_TYPE

Replace TODO_REPLACE_WITH_ENTITY with one of User, Student, Organization, Course, Group, Event or Survey. And TODO_REPLACE_WITH_CONTENT_TYPE needs to be either application/json(recommended) orapplication/xml`. You can also simply open this link in your browser. Don't forget to replace TODO_FLOW_HOST with the hosted flow-instance hostname.

note

This endpoint is only accessible to the admin user.

Entity import order​

Due to current system limitations, you should first import Courses then Groups and then the Events. Otherwise, some entries might no get imported. In that case you will get a warning with the ids of the entries that could not be imported. All other types can be imported in any order. The following order is recommended when making sequential import calls from one system:

  1. Users
  2. Organizations
  3. Students
  4. Courses
  5. Groups
  6. Events
  7. Surveys

Global integrity check​

By default, after each import, an integrity check over the whole database is executed. In this step, it is checked if all references of all the imported data can be resolved (e.g. if each student object has its corresponding user object). If you import multiple entities concurrently, you might want to execute this validation only once at the end. Therefore, you can add to the import URL the query parameter runGlobalIntegrityCheck=false. When set to false the check will be skipped for this request. This parameter is optional and defaults to true.

e.g. https://TODO_FLOW_HOST/import/users?importerId=TODO_REPLACE_WITH_IMPORTER_ID&runGlobalIntegrityCheck=false

Attendance record migration​

The global integrity check also runs automatic attendance record migration when the system config option autoMigrateOrphanedAttendances is enabled.

An attendance record (or request) becomes orphaned in two situations:

  • Event ID changed – the event no longer exists in the course under its old ID (e.g. the upstream CMS assigned a new identifier to the same time slot).
  • Student changed group – the student is now registered in a different group than the one the attendance record refers to.

When either condition is met, Flow resolves the correct target event by matching the original start and end time. The record is then migrated to the event in the student's currently registered group.

note

Because migration runs as part of the global integrity check, you must not suppress the integrity check on the final import call in your sequence. If you use runGlobalIntegrityCheck=false to speed up intermediate import steps, make sure the last call (typically after importing Events) is sent without that parameter, so that the migration runs once at the end.

Records that cannot be resolved unambiguously — for example, because the student is no longer registered for the course, or no event exists at the original time slot in their new group — are left unchanged and counted in the attendanceMigration field of the response.

Date Time format (Date data type)​

For date properties, the ISO 8601 format yyyy-MM-dd'T'HH:mm:ss.SSSX is used, e.g. 2023-03-10T12:30:00.000+01:00 or 2023-03-10T11:30:00.000Z (10 March 2023 at 11:30 o'clock UTC).