Canvas LMS Grade a Student by Section Enrollment

arazzo: 1.0.1
info:
  title: Canvas LMS Grade a Student by Section Enrollment
  summary: Find a student via course section enrollments, then grade their assignment.
  description: >-
    A section-scoped grading flow for Canvas. Because the covered REST surface
    does not expose a create-section operation, this workflow adapts the
    "create section then enroll" theme to a supported pattern: it lists the
    course's student enrollments (which carry the course_section_id), recovers a
    student in the desired section, reads that student's submission for an
    assignment, and posts a grade. Every step spells out its request inline so
    the flow can be read and executed without opening the underlying OpenAPI
    description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-4720.10
  - BC-4740.30
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-4720.10
      capability_name: Enrolment & Registration
      spec: canvas-lms-enrollments-api-openapi.yml
      confidence: 0.85
    - capability_id: BC-4740.30
      capability_name: Marking & Grading Operations
      spec: canvas-lms-submissions-api-openapi.yml
      confidence: 0.85
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: enrollmentsApi
  url: ../openapi/canvas-lms-enrollments-api-openapi.yml
  type: openapi
- name: submissionsApi
  url: ../openapi/canvas-lms-submissions-api-openapi.yml
  type: openapi
workflows:
- workflowId: section-roster-and-grade
  summary: Resolve a section student from enrollments and grade their submission.
  description: >-
    Lists active student enrollments to recover a user and their section, reads
    that user's submission for the assignment, and posts a grade.
  inputs:
    type: object
    required:
    - courseId
    - assignmentId
    - postedGrade
    properties:
      courseId:
        type: string
        description: The Canvas course id.
      assignmentId:
        type: string
        description: The Canvas assignment id to grade.
      postedGrade:
        type: string
        description: The grade to post.
  steps:
  - stepId: listSectionEnrollments
    description: >-
      List the course's active student enrollments, which include the
      course_section_id, to recover a student to grade.
    operationId: listCourseEnrollments
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: type[]
      in: query
      value:
      - StudentEnrollment
    - name: state[]
      in: query
      value:
      - active
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      studentUserId: $response.body#/0/user_id
      sectionId: $response.body#/0/course_section_id
  - stepId: getSubmission
    description: >-
      Read the resolved student's submission for the assignment.
    operationId: getSubmission
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: assignment_id
      in: path
      value: $inputs.assignmentId
    - name: user_id
      in: path
      value: $steps.listSectionEnrollments.outputs.studentUserId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      submissionUserId: $response.body#/user_id
  - stepId: gradeSubmission
    description: >-
      Post the grade to the section student's submission.
    operationId: gradeSubmission
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: assignment_id
      in: path
      value: $inputs.assignmentId
    - name: user_id
      in: path
      value: $steps.listSectionEnrollments.outputs.studentUserId
    requestBody:
      contentType: application/json
      payload:
        submission:
          posted_grade: $inputs.postedGrade
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      grade: $response.body#/grade
      score: $response.body#/score
  outputs:
    sectionId: $steps.listSectionEnrollments.outputs.sectionId
    grade: $steps.gradeSubmission.outputs.grade