openapi.yaml

swagger: '2.0'
info:
  title: OnBase API
  description: Access person information related to OnBase project.
  version: v1
  license:
    name: GNU Affero General Public License Version 3
    url: http://www.gnu.org/licenses/agpl-3.0.en.html
  contact:
    name: IS Data Architecture Team
    url: https://is.oregonstate.edu/data-architecture
    email: isdataarchitecture@oregonstate.edu
schemes:
  - https
host: api.oregonstate.edu
basePath: /v1
externalDocs:
  description: GitHub Repository
  url: https://github.com/osu-mist/onbase-api
consumes:
  - application/json
produces:
  - application/json
security:
  - OAuth2:
      - full
paths:
  /onbase/admissions/{osuId}:
    get:
      summary: Return an admission for an OSU ID
      tags:
        - onBase
        - admissions
      description: Return an admission for an OSU ID
      operationId: getAdmissionById
      parameters:
        - $ref: '#/parameters/osuId'
        - name: applicationNumber
          in: query
          required: false
          description: Application number
          type: integer
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/AdmissionResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '404':
          description: Person record for an OSU ID not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResult'
    patch:
      summary: Update an existing application of an admission
      tags:
        - onBase
        - admissions
      description: Update an existing application of an admission by ID
      operationId: patchAdmissionById
      parameters:
        - $ref: '#/parameters/osuId'
        - $ref: '#/parameters/admissionPatchBody'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/AdmissionResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '404':
          description: Person record for an OSU ID not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '409':
          description: Conflict error
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
  /onbase/financial-aid/{osuId}:
    get:
      summary: Return financial aid data for an OSU ID
      tags:
        - onBase
        - financialAid
      description: Return financial aid data for an OSU ID
      operationId: getFinancialAidById
      parameters:
        - $ref: '#/parameters/osuId'
        - in: query
          name: financialAidYear
          description: |
            Search by financial aid year. Financial aid year is a 4-digit code. For example, for Summer 2018, the value would be 1819
          required: true
          type: string
          pattern: '^\d{4}$'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/FinancialAidResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '404':
          description: Person record for an OSU ID not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResult'
    patch:
      summary: Update existing tracking requirements of a financial aid
      tags:
        - onBase
        - financialAid
      description: Update existing tracking requirement of a financial aid by ID
      operationId: patchFinancialAidById
      parameters:
        - $ref: '#/parameters/osuId'
        - $ref: '#/parameters/financialAidPatchBody'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/FinancialAidResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '404':
          description: Person record for an OSU ID not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '409':
          description: |
            Conflict error, either type is incorrect or the path ID and body ID are not matched
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          $ref: '#/responses/500'
  /onbase/holds/{osuId}:
    get:
      tags:
        - onBase
        - holds
      description: Get a student's current academic holds.
      operationId: getHoldsById
      parameters:
        - $ref: '#/parameters/osuId'
        - in: query
          name: codes
          description: Filter holds by codes
          required: false
          type: array
          collectionFormat: csv
          items: &HoldCode
            type: string
            enum: [AD, AM, AP, AR, AS, AW, BB, BC, BD, BG, BI, BL, BP, BR, BS, BU, CC, CE, CM, CP, CR, CS, CW, DC, DD, DG, DH, DP, DS, DT, EL, EN, EO, EP, ET, FA, GA, GD, GG, GM, GR, HA, HC, HH, HI, HS, HV, IN, IP, IS, IT, LF, LG, N2, N3, N4, N5, NB, ND, NH, NP, NR, PF, R1, R2, R3, R4, R5, R6, R7, R8, R9, RA, RB, RC, RD, RE, RF, RG, RH, RI, RJ, RM, RQ, RT, RY, SF, SL, SR, SS, TP, TR, VM, VT]
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/HoldsResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '404':
          description: Person record for an OSU ID not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResult'
  /onbase/documents:
    post:
      tags:
        - onBase
        - documents
      description: Insert document data
      operationId: postDocument
      parameters:
        - in: body
          name: postDocumentBody
          required: true
          schema:
            properties:
              data:
                type: object
                properties:
                  type:
                    $ref: '#/definitions/DocumentsType'
                  attributes:
                    $ref: '#/definitions/PostDocumentAttributes'
                    additionalProperties: false
                required:
                  - type
                  - attributes
            required:
              - data
      responses:
        '201':
          description: Successful created a document data
          schema:
            $ref: '#/definitions/DocumentsResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResult'
parameters:
  osuId:
    name: osuId
    in: path
    type: string
    required: true
    description: OSU ID of a person
    pattern: '^\d{9}$'
  admissionPatchBody:
    name: admissionPatchBody
    in: body
    schema:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: OSU ID of a person
              pattern: '^\d{9}$'
            type:
              $ref: '#/definitions/AdmissionType'
            attributes:
              type: object
              properties:
                onBaseDocumentType:
                  type: string
                  description: OnBase document type
                  example: ADMS CHNG- Change Request (TermAndMajor)
                additionalChecklistInfo:
                  type: string
                  description: Additional checklist information
                documentReceiveDate:
                  type: string
                  description: The document receive date in Oracle date format (DD-MON-YYYY HH24:MI:SS)
                  example: '20-MAY-2019 00:00:00'
                  pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
                applicationNumber:
                  type: number
                  format: integer
                  description: The application number
                  example: 1
              required:
                - onBaseDocumentType
                - documentReceiveDate
              additionalProperties: false
          required:
            - id
            - type
            - attributes
          additionalProperties: false
      required:
        - data
      additionalProperties: false
    required: true
  financialAidPatchBody:
    name: financialAidPatchBody
    in: body
    schema:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: OSU ID of a person
              pattern: '^\d{9}$'
            type:
              $ref: '#/definitions/FinancialAidType'
            attributes:
              type: object
              properties:
                onBaseDocumentType:
                  type: string
                  description: OnBase document type
                  example: FA Last Day Attended
                financialAidYear:
                  type: string
                  description: |
                   Search terms by financial aid year. Financial aid year is a 4-digit code. For example, for Summer 2018, the value would be 1819
                  example: '1819'
                  pattern: '^\d{4}$'
              required:
                - onBaseDocumentType
                - financialAidYear
              additionalProperties: false
          required:
            - id
            - type
            - attributes
          additionalProperties: false
      required:
        - data
      additionalProperties: false
    required: true
responses:
  '400':
     description: Bad request
     schema:
       $ref: '#/definitions/ErrorResult'
  '500':
     description: Internal server error
     schema:
       $ref: '#/definitions/ErrorResult'
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.oregonstate.edu/oauth2/token
    scopes:
      full: Full access to the API
definitions:
  SelfLink:
    properties:
      self:
        type: string
        format: uri
        description: Self-link of current resource
  Checklist:
    properties:
      admrCode:
        type: string
        description: This field identifies the checklist item required from the applicant
        example: EC
      mandInd:
        type: boolean
        description: This field identifies whether the checklist item is mandatory or optional
        example: true
      receiveDate:
        type: string
        description: The date that the checklist item was received in Oracle date format (DD-MON-YYYY HH24:MI:SS)
        example: '20-MAY-2019 00:00:00'
        pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
      comment:
        type: string
        description: This field identifies a comment about the specific checklist item
        example: Univ of North Dakota
  Application:
    properties:
      termCode:
        type: string
        description: Term code
        example: '201901'
        pattern: '^\d{6}$'
      applicationNumber:
        type: integer
        description: Application number
        example: 3
      statusCode:
        type: string
        description: Status code
        example: 'D'
      statusDate:
        type: string
        description: The status date in Oracle date format (DD-MON-YYYY HH24:MI:SS)
        example: '20-MAY-2019 00:00:00'
        pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
      decisionCode:
        type: string
        description: Application decision code
        example: 'AT'
      decisionDate:
        type: string
        description: The decision date in Oracle date format (DD-MON-YYYY HH24:MI:SS)
        example: '20-MAY-2019 00:00:00'
        pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
      levelCode:
        type: string
        description: Application level code
        example: '02'
      campusCode:
        type: string
        description: Campus code
        example: 'DSC'
      studentTypeCode:
        type: string
        description: Student type code
        example: 'T'
      admitCode:
        type: string
        description: Admit code
        example: 'RA'
      initialCompleteDate:
        type: string
        description: The initial complete date in Oracle date format (DD-MON-YYYY HH24:MI:SS)
        example: '20-MAY-2019 00:00:00'
        pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
      justCompletedInd:
        type: boolean
        description: The indicator shows if the application is just completed
        example: true
      uacPendingInd:
        type: boolean
        description: The indicator shows if the application is still pending in University Admission Committee
        example: true
      startSession:
        type: string
        description: Start session
        example: SOP8
      aswInd:
        type: boolean
        description: Advance standing indicator
        example: true
      currentDocMandInd:
        type: boolean
        description: The indicator shows if the inserted document is a mandatory checklist item
        example: true
      checklist:
        type: array
        items:
          $ref: '#/definitions/Checklist'
  AdmissionResource:
    properties:
      id:
        $ref: '#/definitions/OsuId'
      type:
        $ref: '#/definitions/AdmissionType'
      attributes:
        properties:
          applications:
            type: array
            items:
              $ref: '#/definitions/Application'
      links:
        $ref: '#/definitions/SelfLink'
  AdmissionResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/AdmissionResource'
  AdmissionType:
    type: string
    enum: [admissions]
  TrackingRequirements:
    properties:
      financialAidYear:
        type: string
        description: Financial aid year. This is a 4-digit code. For example, for Summer 2018, the value would be 1819
        pattern: '^\d{4}$'
        example: '1819'
      trackingRequirement:
        type: string
        description: Tracking requirement
        example: ADMIT
      trackingStatusCode:
        type: string
        description: Tracking status code
        example: M
      statusDate:
        type: string
        description: The status date in Oracle date format (DD-MON-YYYY HH24:MI:SS)
        example: '20-MAY-2019 00:00:00'
        pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
  FinancialAidResource:
    properties:
      id:
        $ref: '#/definitions/OsuId'
      type:
        $ref: '#/definitions/FinancialAidType'
      attributes:
        properties:
          trackingRequirements:
            type: array
            items:
              $ref: '#/definitions/TrackingRequirements'
      links:
        $ref: '#/definitions/SelfLink'
  FinancialAidResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/FinancialAidResource'
  FinancialAidType:
    type: string
    enum: [financialAid]
  HoldsResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/HoldsResource'
  HoldsResource:
    properties:
      id:
        $ref: '#/definitions/OsuId'
      type:
        type: string
        enum: [holds]
      attributes:
        properties:
          holds:
            type: array
            items:
              properties:
                fromDate:
                  description: The date this hold becomes effective.
                  type: string
                  format: date
                  example: 2019-12-31
                toDate:
                  description: The date this hold expires.
                  type: string
                  format: date
                  example: 2020-12-31
                description:
                  description: Description of the hold.
                  type: string
                  example: Missing requirements.
                processesAffected:
                  description: Processes affected by the hold.
                  type: array
                  items:
                    type: string
                    example: Graduation
                reason:
                  description: The reason the hold is on the student's record.
                  type: string
                  example: CS 161
                code: *HoldCode
                organizationCode:
                  type: string
                  description: Organization code of the hold.
                  example: REGS
                organizationDescription:
                  type: string
                  description: Organization description of the hold.
                  example: Registration Office
                releasedInd:
                  type: boolean
                  description: The released indicator of the hold.
                  example: true
      links:
        $ref: '#/definitions/SelfLink'
  DocumentsType:
    type: string
    enum: [documents]
  PostDocumentAttributes:
    properties:
      documentId:
        type: string
        description: OnBase document ID
        example: '123456'
        pattern: ^\d+$
      fieldName:
        type: string
        description: Field name in document
        example: test field
      fieldValue:
        type: string
        description: Value of field in document
        example: test 123
      indexKey:
        type: string
        description: Index key keyword value for document in OnBase
        example: '123456789_1234'
      docTypeNumber:
        type: integer
        description: OnBase document type number
        example: 123
      instance:
        type: string
        description: Identifies which OnBase instance
        example: 'UT2'
      version:
        type: integer
        description: OnBase document version
        example: 0
    required:
      - documentId
      - fieldName
      - indexKey
      - docTypeNumber
      - instance
  DocumentsResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/DocumentsResource'
  DocumentsResource:
    properties:
      id:
        type: string
        description: Unique document internal ID
      type:
        $ref: '#/definitions/DocumentsType'
      attributes:
        allOf:
          - $ref: '#/definitions/PostDocumentAttributes'
          - properties:
              seqNo:
                type: integer
                description: Sequence number of repeating field
                example: 1
              activityDate:
                type: string
                description: The date that this record was last changed in Oracle date format (DD-MON-YYYY HH24:MI:SS)
                example: '12-Jan-2021 00:00:00'
                pattern: '^\d{2}-[A-Z]{3}-\d{4} \d{2}:\d{2}:\d{2}$'
              userId:
                type: string
                description: User who made the last change
                example: ONBASE
  OsuId:
    properties:
      id:
        type: string
        description: OSU ID of a person
        pattern: '^\d{9}$'
  ErrorObject:
    properties:
      status:
        type: string
        description: HTTP status code
        example: '123'
      title:
        type: string
        description: A short, user readable summary of the error
        example: Not Found
      code:
        type: string
        description: An application-specific error code
        example: '1234'
      detail:
        type: string
        description: A long description of the error that may contain instance-specific details
      links:
        properties:
          about:
            type: string
            format: uri
            description: A link to further information about the error
            example: https://developer.oregonstate.edu/documentation/error-reference#1234
  ErrorResult:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorObject'