Canvas LMS Grade a Discussion-backed Assignment

arazzo: 1.0.1
info:
  title: Canvas LMS Grade a Discussion-backed Assignment
  summary: Locate a discussion topic's graded assignment, then grade a student's discussion submission.
  description: >-
    A discussions grading flow for Canvas. Graded discussions in Canvas are
    backed by an assignment, so this workflow lists a course's discussion topics
    to recover the assignment id behind a graded discussion, reads the student's
    submission for that assignment, and posts a grade. This adapts the
    announcements/discussions theme to the operations the covered REST surface
    actually supports. 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-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-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: discussionsApi
  url: ../openapi/canvas-lms-discussions-api-openapi.yml
  type: openapi
- name: submissionsApi
  url: ../openapi/canvas-lms-submissions-api-openapi.yml
  type: openapi
workflows:
- workflowId: grade-discussion-submission
  summary: Resolve a graded discussion's assignment and grade a student submission.
  description: >-
    Lists discussion topics to find the graded discussion's backing assignment
    id, reads the student's submission for it, and posts a grade and comment.
  inputs:
    type: object
    required:
    - courseId
    - userId
    - postedGrade
    properties:
      courseId:
        type: string
        description: The Canvas course id.
      userId:
        type: string
        description: The Canvas user id of the student whose discussion submission is graded.
      postedGrade:
        type: string
        description: The grade to post.
      textComment:
        type: string
        description: Optional feedback comment to attach.
  steps:
  - stepId: listDiscussions
    description: >-
      List the course discussion topics to recover the assignment id that backs
      the first graded discussion.
    operationId: listDiscussionTopics
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: order_by
      in: query
      value: recent_activity
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      discussionAssignmentId: $response.body#/0/assignment_id
  - stepId: getSubmission
    description: >-
      Read the student's submission for the discussion's backing assignment.
    operationId: getSubmission
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: assignment_id
      in: path
      value: $steps.listDiscussions.outputs.discussionAssignmentId
    - name: user_id
      in: path
      value: $inputs.userId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      submissionUserId: $response.body#/user_id
  - stepId: gradeSubmission
    description: >-
      Post the grade and optional comment to the student's discussion
      submission.
    operationId: gradeSubmission
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: assignment_id
      in: path
      value: $steps.listDiscussions.outputs.discussionAssignmentId
    - name: user_id
      in: path
      value: $inputs.userId
    requestBody:
      contentType: application/json
      payload:
        submission:
          posted_grade: $inputs.postedGrade
        comment:
          text_comment: $inputs.textComment
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      grade: $response.body#/grade
      score: $response.body#/score
  outputs:
    assignmentId: $steps.listDiscussions.outputs.discussionAssignmentId
    grade: $steps.gradeSubmission.outputs.grade