Import Entities

Each section describes the response body of one endpoint. Flow expects a JSON array of the objects described in the tables. Optional properties are marked with a ? in the type column and may be omitted or returned as null. Nested properties are written using dot notation (e.g. groups.events.start). See General for authentication, IDs and the date format.

User

URL: GET https://TODO_API_HOST/users

note

Student data is embedded in the user via the optional student object. It is only present for users that are students; staff-only users omit it. A student's course/group registrations are not part of the user — they are part of the course (see the Course entity below).

Body

field	type	description
id	String	Unique identifier of the user.
firstName	String	First name of the user.
lastName	String	Last name of the user.
username	String?	If set, this can be used to log in instead of the email.
staffEmail	String?	Can be used to log in and is used to send email notifications to the user.
campusManagementRoles	String[]?	Roles of the user within the campus management system. Used for the role mapping. Also see the role mapping settings in Flow.
student	object?	Student data. Only set for users that are students.
student.studentEmail	String?	Can be used to log in and is used to send email notifications to the user.
student.matriculationNumber	String?	Matriculation number of the student.
student.studyProgram	String?	Name of the study program of the student.
passwordOrHash	String?	Hashed or plaintext password. If hashed then `passwordPreHashing` must be specified. See documentation of the DatabasePasswordLoginProvider for security considerations.
passwordPreHashing	object?	Describes the hashing method used to generate `passwordOrHash` from the user's password. Use `null` if the password is sent in plain text or another LoginProvider than DatabasePasswordLoginProvider is used. Also see documentation of the DatabasePasswordLoginProvider.
passwordPreHashing.algorithm	String	Hashing algorithm that is used. For available options, see DatabasePasswordLoginProvider documentation.
passwordPreHashing.saltMode	String	Salt mode to use. For available options, see DatabasePasswordLoginProvider documentation.
passwordPreHashing.salt	String?	Salt that is used. Use `null` if `saltMode` is `NONE`.
passwordPreHashing.hmacKey	String?	The Hmac key that is used. Only needed if `algorithm` specifies a Hmac algorithm.
passwordPreHashing.pbeInfos	object?	Configuration for the PBE algorithm. Only needed if `algorithm` specifies a PBE algorithm.
passwordPreHashing.pbeInfos.iterationCount	int	Iteration count used for PBE.
passwordPreHashing.pbeInfos.keyLength	int	Key length used for PBE.

Example Response

GET https://TODO_API_HOST/users
Authorization: Bearer TODO_REPLACE_WITH_API_SECRET

200 OK
[
  {
    "id" : "student1",
    "firstName" : "Julia",
    "lastName" : "Jungmair",
    "student" : {
      "studentEmail" : "student1@example.org",
      "matriculationNumber" : "50431165",
      "studyProgram" : "Computer Science"
    }
  },
  {
    "id" : "prof2",
    "firstName" : "Klaus",
    "lastName" : "Klammer",
    "campusManagementRoles" : [ "CM_ROLE_EXEMPTION_COMMENTER" ],
    "staffEmail" : "prof2@example.org",
    "passwordOrHash" : "ZGFsZGVtbzEyMw==",
    "passwordPreHashing" : {
      "algorithm" : "PBEWithHmacSHA512AndAES_256",
      "salt" : "DemoSalt",
      "saltMode" : "PBE_ALGORITHM",
      "pbeInfos" : {
        "iterationCount" : 2000,
        "keyLength" : 512
      }
    }
  }, ...
]

Organization

URL: GET https://TODO_API_HOST/organizations

note

If you do not need the organizations concept, you still have to provide one root/default organization to attach all courses to that single organization.

Body

field	type	description
id	String	Unique identifier of the organization.
name	String	Display name of the organization.
moderatorUserIds	String[]	Unique identifiers of users which have moderator access to this organization.
msTeamsModeratorUserIds	String[]?	Unique identifiers of users which have moderator access for the Microsoft Teams plugin.

Example Response

GET https://TODO_API_HOST/organizations
Authorization: Bearer TODO_REPLACE_WITH_API_SECRET

200 OK
[
  {
    "id" : "organisation1",
    "name" : "Department of Mathematics",
    "moderatorUserIds" : [ "manager1", "manager2" ],
    "msTeamsModeratorUserIds" : [ "manager1" ]
  }, ...
]

Course

URL: GET https://TODO_API_HOST/courses?semesterId={semesterId}

Flow requests this endpoint once per configured semester, passing the semesterId query parameter, and the API must return only the courses of that semester to keep the response size down. The semesterId is found in Semesters in the table column Semester ID.

Groups and events are returned as part of the course: a course contains its groups, and each group contains its events. A group also lists the students registered to it in studentUserIds.

If you do not need the groups concept, you still have to return one default group for each course to attach all events of that course to that single group. If an event takes place for multiple groups, you have to return a copy of it within each group's events.

Body

field	type	description
id	String	Unique identifier of the course.
organizationId	String	Unique identifier of the organization the course belongs to.
number	String	Internal number of the course.
name	String	Display name of the course.
semesterId	String	Unique identifier of the semester which the course belongs to (see Semesters-Configuration in Flow).
requiredPresenceRate	int?	Presence rate that is required to pass the course (0 - 100). Defaults to the `defaultPresenceRate` set in the System Configuration.
groupRegistrationStartDate	Date?	Start date and time for the group registration. Users listed in `studentUserIdsWithCustomGroupRegistration` can register for a group in this course beginning with this date. (When imported, the value cannot be changed in the Course Settings.)
groupRegistrationEndDate	Date?	End date and time for the group registration. (When imported, the value cannot be changed in the Course Settings.)
menuLinks	object[]?	List of links which should be shown on the course page.
menuLinks.title	String	Title of the link to be displayed.
menuLinks.description	String	Description for the link/action. Will be shown beneath the title or when hovering the button.
menuLinks.url	String	The URL to open on click. It can be a URL to a Flow HTML module or to an external system.
menuLinks.inline	boolean	If `true` a button will be shown in the top bar. Otherwise, the item will be shown in the 3-dot menu.
autoApproveAttendanceRequests	boolean?	If `true` attendance requests will be auto-approved when requested by the student and can be later denied by moderators.
attendanceRequestDeadlineDays	int?	If set it overwrites `attendanceRequestDeadlineDays` in the System Configuration for the particular course.
studentUserIdsWithCustomGroupRegistration	String[]?	Unique identifiers of the students (users) that have to register to a group in this course themselves.
groups	object[]	Groups of the course. A course must contain at least one group.
groups.id	String	Unique identifier of the group within the course.
groups.name	String	Display name of the group.
groups.sizeLimit	int?	Maximum number of students that can be in this group. Use a negative number for unlimited. Only relevant for courses which use the Flow group registration. (When imported, the value cannot be changed in the Course Settings.)
groups.lecturerUserIds	String[]?	Unique identifiers of the users who are lecturers for this group of the course.
groups.studentUserIds	String[]	Unique identifiers of the students (users) registered in this group.
groups.events	object[]	Events of the group.
groups.events.id	String	Unique identifier of the event.
groups.events.start	Date	Start date and time of the event.
groups.events.end	Date	End date and time of the event.
groups.events.location	String?	Location where the event takes place.
groups.events.teachingUnits	double?	Number of teaching units. Used for the presence rate calculation. Defaults to `1.0`. When set to `0.0` the event is considered as optional and does not have any influence on the presence rate.
groups.events.type	String?	Use `ONLINE_TEAMS` for events that should be synced with the Microsoft Teams Plugin. (Only relevant for the MS Teams Plugin)
groups.events.lecturerUserId	String?	Unique identifier of the user which is a lecturer for this event.
groups.events.isSharedAcrossGroups	boolean?	Should be set to `true` in case this event is shared across all groups. Currently only relevant for the MS Teams Plugin. If `true`, a single Teams event is created and shared across all groups instead of one per group. Defaults to `false`.
groups.events.onlineUrl	String?	URL to an online meeting. Shown to students in the event detail view as a join link.

Example Response

GET https://TODO_API_HOST/courses?semesterId=2026W
Authorization: Bearer TODO_REPLACE_WITH_API_SECRET

200 OK
[
  {
    "id" : "course-0",
    "organizationId" : "organisation1",
    "number" : "FLOW-000",
    "name" : "Economics",
    "semesterId" : "2026W",
    "requiredPresenceRate" : 75,
    "groupRegistrationStartDate" : "2023-03-11T08:00:00.000+01",
    "groupRegistrationEndDate" : "2023-03-17T20:00:00.000+01",
    "menuLinks" : [
      {
        "title" : "Moodle Course",
        "description" : "Go to the moodle course",
        "url" : "https://moodle.org/course/course-0",
        "inline" : true
      }
    ],
    "autoApproveAttendanceRequests" : true,
    "attendanceRequestDeadlineDays" : 7,
    "studentUserIdsWithCustomGroupRegistration" : [ "student9" ],
    "groups" : [
      {
        "id" : "group-1",
        "name" : "Group 1",
        "sizeLimit" : null,
        "lecturerUserIds" : [ "prof1" ],
        "studentUserIds" : [ "student1", "student2" ],
        "events" : [
          {
            "id" : "course0-group1-event10",
            "start" : "2023-03-20T15:00:00.000+01",
            "end" : "2023-03-20T17:15:00.000+01",
            "location" : "Online",
            "teachingUnits" : 3.0,
            "lecturerUserId" : "prof1",
            "isSharedAcrossGroups" : false,
            "onlineUrl" : "https://meet.example.org/course0-event10"
          }
        ]
      }
    ]
  }, ...
]

Survey

URL: GET https://TODO_API_HOST/surveys

info

Surveys are only imported when enableSurvey is enabled in the System Configuration. If it is disabled, the surveys endpoint does not have to be implemented, or it can simply return an empty array ([]).

Body

Each item is either a free-text or a choice question. Set exactly one of items.freetext or items.choice accordingly.

field	type	description
id	String	Unique identifier of the survey.
courseIds	String[]	Course ids on which survey should be shown for each event.
items	object[]	Questions for survey.
items.id	String	Id of the question.
items.optional	boolean?	If `true` question is optional.
items.freetext	object?	Set for a free-text question. Exactly one of `freetext` or `choice` must be set per item.
items.freetext.question	object	Map of language to localized question. Currently supported are `en`, `de` and `si`. `en` is required.
items.freetext.placeholder	object?	Map of language to localized placeholders. Currently supported are `en`, `de` and `si`.
items.choice	object?	Set for a choice question. Exactly one of `freetext` or `choice` must be set per item.
items.choice.question	object	Map of language to localized question. Currently supported are `en`, `de` and `si`. `en` is required.
items.choice.options	object[]	Options for user to select.
items.choice.options.id	String	Id of the answer.
items.choice.options.value	object	Map of language to localized answer. Currently supported are `en`, `de` and `si`. `en` is required.
items.choice.multipleChoice	boolean?	If `true` user can select multiple options in question.
items.choice.otherOption	boolean?	If `true` user can input a custom String if none of the options fit.

Example Response

GET https://TODO_API_HOST/surveys
Authorization: Bearer TODO_REPLACE_WITH_API_SECRET

200 OK
[
  {
    "id": "demoSurvey1",
    "courseIds": [
      "course-0",
      "course-1"
    ],
    "items": [
      {
        "id": "1",
        "choice": {
          "question": {
            "en": "How satisfied are you with the course?",
            "de": "Wie zufrieden sind Sie mit dem Kurs?",
            "si": "Kako zadovoljni ste s predmetom?"
          },
          "options": [
            {
              "id": "1",
              "value": {
                "en": "Very satisfied",
                "de": "Sehr zufrieden",
                "si": "Zelo zadovoljen"
              }
            },
            {
              "id": "2",
              "value": {
                "en": "Satisfied",
                "de": "Zufrieden",
                "si": "Zadovoljen"
              }
            }
          ],
          "multipleChoice": false,
          "otherOption": false
        }
      },
      {
        "id": "2",
        "optional": true,
        "freetext": {
          "question": {
            "en": "Anything to add about the course?",
            "de": "Ist noch etwas zum Kurs zu sagen?",
            "si": "Želiš kaj dodati o predmetu?"
          },
          "placeholder": {
            "en": "Your feedback",
            "de": "Ihr Feedback",
            "si": "Vaše povratne informacije"
          }
        }
      }
    ]
  },
  ...
]

If something is missing or unclear, please contact us.

User​

Body​

Example Response​

Organization​

Body​

Example Response​

Course​

Body​

Example Response​

Survey​

Body​

Example Response​

User

Body

Example Response

Organization

Body

Example Response

Course

Body

Example Response

Survey

Body

Example Response