Progress Prototype

openapi: 3.0.0
info:
  title: Progress API
  version: '0.0.5'
  description: |-
    This API defines progress about specific learning materials (assignable Units) in the course to report to the `Leermiddelendashboard`. Main goal is to inform teachers on progress (which activities are completed) and possible indication that the activity was completed, but needs attention of the teacher. 

    Progress is reported on Learning materials on the level of Assignable Units within a Course in the Course API. 
    Progress is reported when an activity is started or completed, not while the activity is in progress. If the activity is adaptive and will take more time for one student due to adaptive levels, that is not reported.

    Activities have a life cycle of not-started, started, completed. The not started is the default and will not be reported, unless (for some reason) the status goes back to not-started. The abandoned state is to indicate that the activity was started, but will never be completed (optional).

    The API does not force the supplier of the learning material to use a standard for the indication about the quality of the progress. It is optional to indicate a signal and/or pleaseFollowUp to the `Leermiddelendashboard`.
    This provides the supplier a way to tell the Teacher via the `Leermiddelendashboard` that the progress was not standard and the Teacher is advised to have a look at the more detailed dashboard (with a direct url) within the `Gebruiksomgeving digitaal leermateriaal`.
    A supplier can provide any scale (1-10, average, good, bad) by adding this as text. The `Leermiddelendashboard` should not try to combine these indications for a complete chapter or paragraph.

    Consent is required to exchange Progress information from the `Gebruiksomgeving digitaal leermateriaal` to the `Leermiddelendashboard`.
    
  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
    
    schemaVersion:
      type: string
      description: |
        Schema version of this API using semantic versioning 2.0.0.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.0.5
    
    SimpleProgress:
      title: SimpleProgress
      type: object
      x-tags:
        - Progress
      x-examples:
        example-1:
          id: '123-bigstring-or-guid-does-not-matter-but-unique-for-this-progress-statement'
          schemaVersion: 0
          eckId: 'eck1'
          assignableUnitId: '1234566'
          courseId: 'english-22-high'
          status: 'completed'
          timestamp: '2017-07-21T17:32:28Z'
          additionalInfo: ':)'
          detailsUrl: 'https://course.publisher.com/analysis/1234566/eck1'
          pleaseFollowUp: False
      description: 'The SimpleProgress Event that is send by the `Gebruiksomgeving digitaal leermateriaal` to the `Leermiddelendashboard` to report progress on an Assignable Unit in a Course by a specific Student.'
      properties:
        id:
          type: string
          description: Unique id
        student:
          description: 'The Student for which progress is reported.'
          $ref: '#/components/schemas/UserReference'
        school:
          description: 'The School of the Student.'
          $ref: '#/components/schemas/SchoolReference'
        assignableUnitId:
          type: string
          description: 'Assignable Unit for which progress is reported. This is strongly linked to an identifier of an Assignable Unit in the CourseStructure object in the Course API.'
        courseId:
          type: string
          description: 'Optional identifier of the CourseStructure where the Assignable Unit belongs to.'
        status:
          type: string
          description: 'New status of the activity of the Student regarding the Learning Material.'
          enum:
            - not-started
            - started
            - completed
            - abandoned
        timestamp:
          type: string
          format: date-time
          description: |
            Timestamp of the activity that lead to the Event.
            Format: Conform openapi in ZULU time zoals gespecificeerd in RFC 3339, section 5.6
        additionalInfo:
          type: string
          description: |-
            Additional signal to show to teachers about this progress. This could be a signal that all is fine, or that the activity was finished, but not successful or with so much effort that the teacher is advised that to look at the LA systems dashboards. 
            field is free format, bust should be very short. eg "good","average", single digit, smileys, "!" (also see detailsUrl)
          maxLength: 15
          example: ':)'
        detailsUrl:
          type: string
          description: 'Deeplink to the page of the LA where a teacher can get details on this progress event.'
        pleaseFollowup:
          type: boolean
          default: False
          description: |-
            Boolean to indicate that the additional info and detailsUrl are provided as an invite to have a closer look at this progress.
            This can be used by the `Leermiddelendashboard` to show a list of signals that the teacher should followup
      required:
        - id
        - student
        - school
        - assignableUnitId
        - courseId
        - status
        - timestamp
    
    UserReference:
      type: object
      title: UserReference
      properties:
        userMasterIdentifier:
          type: string
          description: |
            The primary identifier for a User.
            For Students the ECK iD is used.
            For Employees this value is empty. There is no primary identifier for Employees.
            (either userMasterIdentifier or userIds is required)
        userIds:
          type: array
          description: |
            A secondary identifier for a User. This value is used whenever the primary identifier is not available.
            For Employees this value is mandatory.
            (either userMasterIdentifier or userIds is required)
          items:
            type: object
            properties:
              userId:
                type: string
              userIdType:
                type: string
                enum:
                  - NEPPI # nlPersonProfileId – value can be used for students and employees
                  - BPI # Basispoort ID – value can be used for students and employees
                  - eduID # eduID identifier – value can be used for students and employees
                  - NEPRI # nlPersonRealId – value can be used for students only
                  - ASI # Las-key – value can be used for students only
                  - eckId # ECK iD – value can be used for employees only, eckId is userIdType for userMasterIdentifier for students
            required:
              - userId
              - userIdType
    
    SchoolReference:
      type: object
      title: SchoolReference
      description: 'A reference to a School organisation.'
      properties:
        organisationMasterIdentifier:
          type: string
          description: |
            The primary identifier for a School. For Schools the `OnderwijsaanbiederId` is used.
            (either organisationMasterIdentifier or organisationIds is required)
          example: '104A158' # De Mariënborn
        organisationIds:
          type: array
          description: |
            A secondary identifier for the School. This value is used whenever the primary identifier is not available.
            (either organisationMasterIdentifier or organisationIds is required)
          items:
            type: object
            properties:
              organisationId:
                type: string
              organisationIdType:
                type: string
                enum:
                  - OIE_CODE # Onderwijsinstellingserkenningcode e.g. 09QQ (Marienbornschool)
                  - BP_ID # Basispoort gegenereerde identifier voor de school.
                  - DD_ID # Door de Centrale Registratie van Edu-iX gegenereerde DigiDeliveryId van de school.
                  - AS_ID # Door het Leerlingadministratiesysteem gegenereerde identifier van de school.
            required:
              - organisationId
              - organisationIdType

    StatusResponse:
        title: StatusResponse
        type: object
        description: 'Functional status code and status message.'
        properties:
          status:
            type: integer
            description: 'See functional status codes within the Documentation.'
          statusMessage:
            type: string
            description: 'See functional status messages within the Documentation.'
        required:
          - status
  
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            eduv.progress: scope to send progress messages to a `Leermiddelendashboard`

paths: 
  /progress/{id}:
    put:
      operationId: putSimpleProgress
      summary: The REST create request message for the putProgressId() API call.
      tags: 
        - Leermiddelendashboard
      description: |
        To create a new SimpleProgress object or change an existing SimpleProgress object.
      security:
        - OAuth2:
            - eduv.progress
      parameters: 
        - name: id
          in: path
          description: |
              The unique identifier for the Progress object.
          required: true
          schema: 
            type: string
      requestBody:
        description: |
          The progress data that is to be stored.
        content: 
          application/json: 
            schema: 
              $ref: "#/components/schemas/SimpleProgress"
        required: true
      responses: 
        "202" : 
          description: |
            The object has been successfully stored in the progress administration.
        "400" : 
          description: |
            This is the error response for HTTP status code 400.
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/StatusResponse"
        "401" : 
          description: |
            This is the error response for HTTP status code 401.
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/StatusResponse"
        "403" : 
          description: |
            This is the error response for HTTP status code 403.
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/StatusResponse"
x-tags:
  - name: Progress