Data model

Example of an interface exposing data consumable by AppScho

This page attempts to introduce some example of the minimal data AppScho needs to function properly. This list is a subset of the features and data that should be provided by your ERP or any other system in your ecosystem, and may need to be enriched further.

The recommended format for these exchanges is JSON through an HTTP API. For such a "simple" interface contract, a REST model is preferred to some complex RPC system such as SOAP.

Please note that a unique ID is required for each individual item returned by the API. This requirement exists for AppScho to be able to track changes properly.

User authentication

This section does not cover actual user authentication, but rather authorization of API request coming from AppScho on behalf of a logged in user. Two methods are available:

• Use the ad-hoc authentication system in use in the school. Here, the API request is authenticated with some transient credentials (usually, an authentication token) which must be checked by the upstream API.

• Rely on AppScho to authenticate and guard access to the upstream API. In this case, the upstream API must build a trust relationship with AppScho's infrastructure, which is the one that is going to be authenticated to your services, through service accounts, for example. In this case, the user student will be provided through a parameter.

You can get details on the authentication methods supported by AppScho is the dedicated sections of this documentation.

User information

When the user is authenticated, we need to retrieve some basic information about their identity, some purely cosmitic, some required for additional functionnality. The required information are the following: et son profil au sein de l'établissement. Les données essentielles étant les suivantes :

• firstname

• lastname

• list of group IDs they belong to, if you want to target them as part of an audience in our Messaging feature (these groups are used within iOS and Android's push notification systems, and therefore need to remain simple IDs (letters, numbers and dashes).

Some other data can be retrieved and used if available:

• their picture (HTTPS URL or base64-encoded data)

• program in which the student is enrolled

• their promotion

• number of ECTS credits obtained

{
  "firstname": "Antoine",
  "lastname": "POPINEAU",
  "picture": "https://server.school.com/xxx.png",
  "program": "Master in Management",
  "promotion": "2019",
  "credits": 176,
  "groups": [
    "master",
    "master-management",
    "promotion-2019"
  ]
}

Audiences

On top of the list of groups returned within the user information (see above), AppScho needs to periodically synchronize the complete list of available groups in order to display them to your institution's administrators in the My AppScho platform. These groups must have a unique ID (the same returned for a user) and a human-readable label:

[
  {
    "id": "master",
    "label": "Master students"
  },
  {
    "id": "master-management",
    "label": "Master students in Management"
  }
]

Grade report

Here, we need to retrieve a list of exams, with attributes related to it, for example:

• subject name

• exam date

• mark

• number of ECTS credits

Those exams can be organized in an arbitrary hierarchy allowing to sort the exam in school year, semester, module, etc. We recommend to limit as much as possible the depth of this hierarchy in order to optimize the user experience on a mobile device.

[
  {
    "uid": "Y2018",
    "title": "2018-2019",
    "children": [
      {
        "uid": "Y2018S1",
        "title": "Semester 1"
        "grade": "18.3"
        "children": [
          {
            "uid": "Y2018S1-1234",
            "title": "Management 101",
            "grade": "16",
            "comment": "Very good job!"
          }
        ]
      },
      {
        "uid": "Y2018S2",
        "title": "Semester 2"
        "children": []
      }
    ]
  }
]

Timetable

The timetable should be a simple, flat, list of event containing, at least, the following information:

• a unique ID for the event

• the name of the event (usually, the class name)

• start date and time

• end date and time

The unique ID is used by AppScho to detect if an event was modified when comparing two iterations of timetable. It is therefore very important that this ID is globally unique and stable.

The format of the received date is flexible as long as it is accurate (full date with time and timezone).

Each event can also, if available, add the following information:

• the name of the room / location where the event is happening

• name of the professor

• a simple description of the event

• a link to an LMS platform for the class

• a link to the visioconferencing platform for the class

• the color which should be displayed for the event on the planning (hexadecimal)

[
  {
    "uid": "2016-1234567890",
    "title": "Market strategy",
    "start": "2017-02-12T09:30:00+0200",
    "end": "2017-02-12T11:30:00+0200",
    "location": "Building B - Room 302",
    "teacher": "Antoine POPINEAU",
    "description": "MS course",
    "platform_link": "https://example.link.com"
    "visio_link": "https://example.visio.com/l/meetup-join/123456"
    "color": "0000FF"
  }
]

Custom alerts

Here we retrieve a list of alerts. Each alert should have a unique ID, a title and a description. Those will be displayed on the app's dashboard and will remain as long as your service keeps sending it.

[
  {
    "uid": "123456789",
    "title": "Internship contract",
    "desc": "Please fill in and sign your internship contract before 01/01/2020"
  }
]

Absences

A list of attendance event for a student with, at least, the following information:

• name of related class

• start and and date and time of the attendance event

• a boolean indicating if the absence is justified or not

Optionnaly, if available, we can retrieve and display the justification of the absence and a comment.

[
  {
    "class": "Market strategy",
    "start": "2017-02-13T14:00:00+0200",
    "end": "2017-02-13T15:00:00+0200",
    "justified": true,
    "justification": "The student provided their doctor's note.",
    "comment": "The student did not show up in class.",
    "teacher": "Antoine POPINEAU"
  }
]

Directory

A directory interface should allow us to perform a search with terms provided by the user and return a list of persons matching them.

Each person entity returned should have at least a unique ID, the firstname and the lastname. Optionnally, other attributes can be used:

• The role the person has in the institution (student, teacher, staff, alumni, etc.)

• Their email addresses

• Their phone numbers

• A picture

• An office number

[
  {
    "id": 18745,
    "firstname": "Antoine",
    "lastname": "POPINEAU",
    "type": "teacher",
    "email": "[e-mail]",
    "phone": "[phone]",
    "picture": "https://school.edu/pictures/18745.jpg"
  }
]

Documents

The list of documents shoudl have the same structure as the grade report, meaning an arbitrary hierachy of "directories" and "files", which will be reconstructed in the user's app.

Each level can contain children (in which case, the level is considered a directory). If a node of the hierarchy does not contain any children, it is considered a document and should have additional information on how to display and retrieve this document. An important element to note: the document should be downloadable through HTTPS directly by the mobile terminal (not go through AppScho's servers), without external authentication, or be authenticated through the provided URL, for instance with an included token.

[
  {
    "uid": "26f88685-b775-446d-a2e7-81cd2f8160d2",
    "title": "Attestations de scolarité",
    "children": [
      {
        "uid": "8fd8cbae-dcf3-46f6-9311-f4d731e0b6c5",
        "title": "Attestation de scolarité 2020",
        "url": "https://example.com/files/fa39f0ab-53bd-4f81-b108-61b585b0b6b.pdf?token=c5af0d6d-14da-4865-b59d-25a84a0497c1",
        "filename": "Education certificate 2020.pdf"
      },
      {
        "uid": "07109524-6432-4797-b5cd-812b111def7c",
        "title": "Attestation de scolarité 2019",
        "url": "https://example.com/files/7230eaca-1062-4987-8945-c173640b9c76.pdf?token=c5af0d6d-14da-4865-b59d-25a84a0497c1",
        "filename": "Education certificate 2019.pdf"
      }
    ]
  }
]

It is possible to hint at the name the final document should have once downloaded through an additional attribute (here, filename).

Payments

The Payments feature can display two kinds of information:

• a list of "situations" that can display at least one balance

• a list of payments with their respective statuses

A situation item should contain the following attributes:

• Unique ID

• Title

• Description

• Balance (positive or negative)

A payments item should include the following information:

• Unique ID

• Title

• Description

• Amount

• Date of payment

• Boolean indicating if the item was paid for

• Boolean indicating if the payments failed for any reason

• A comment, description or failure reason

{
  "balances": [
    {
      "uid": "956dc15c-ada5-4424-80c4-0efc51c8caaa",
      "title": "Année 2019/2020",
      "description": "Tuition fees 2019/2020",
      "balance": -200.5
    }
  ],
  "payments": [
    {
      "uid": "956dc15c-ada5-4424-80c4-0efc51c8caaa",
      "title": "Monthly fee - December 2020",
      "amount": 100.0,
      "paid": true,
      "failed": false,
      "paid_on": "2020-12-01T00:00:00+01:00"
    }
  ]
}