arazzo: 1.0.1
info:
  title: Canvas LMS Find or Create Assignment
  summary: Search a course for an assignment by name and create it only when it is missing.
  description: >-
    An idempotent authoring flow for Canvas. The workflow searches a course's
    assignments for one matching the supplied name and then branches: when a
    match is found it reads that existing assignment, and when no match is found
    it creates a new assignment. This avoids duplicating assignments when a
    sync job runs repeatedly. 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
sourceDescriptions:
- name: canvasApi
  url: ../openapi/canvas-lms-rest-api-openapi.yml
  type: openapi
workflows:
- workflowId: find-or-create-assignment
  summary: Upsert an assignment into a course by name, creating it only if absent.
  description: >-
    Searches the course assignments for the supplied name; if one exists it is
    read back, otherwise a new assignment is created.
  inputs:
    type: object
    required:
    - courseId
    - name
    - pointsPossible
    properties:
      courseId:
        type: string
        description: The Canvas course id to search and write into.
      name:
        type: string
        description: The assignment name to search for and create if missing.
      pointsPossible:
        type: number
        description: The maximum points for the assignment when it must be created.
  steps:
  - stepId: searchAssignments
    description: >-
      Search the course assignments using the supplied name as the search term,
      returning matching assignments.
    operationId: listAssignments
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: search_term
      in: query
      value: $inputs.name
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      matchedAssignmentId: $response.body#/0/id
    onSuccess:
    - name: assignmentExists
      type: goto
      stepId: readExisting
      criteria:
      - context: $response.body
        condition: $.length > 0
        type: jsonpath
    - name: assignmentMissing
      type: goto
      stepId: createNew
      criteria:
      - context: $response.body
        condition: $.length == 0
        type: jsonpath
  - stepId: readExisting
    description: >-
      Read the matched assignment back by id to return its full record.
    operationId: getAssignment
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    - name: assignment_id
      in: path
      value: $steps.searchAssignments.outputs.matchedAssignmentId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      assignmentId: $response.body#/id
      name: $response.body#/name
    onSuccess:
    - name: done
      type: end
  - stepId: createNew
    description: >-
      Create a new assignment with the supplied name and point value when no
      existing assignment matched.
    operationId: createAssignment
    parameters:
    - name: course_id
      in: path
      value: $inputs.courseId
    requestBody:
      contentType: application/json
      payload:
        assignment:
          name: $inputs.name
          points_possible: $inputs.pointsPossible
          submission_types:
          - online_text_entry
          published: true
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      assignmentId: $response.body#/id
      name: $response.body#/name
  outputs:
    existingAssignmentId: $steps.readExisting.outputs.assignmentId
    createdAssignmentId: $steps.createNew.outputs.assignmentId